Crasman Studio API v2.0
Yleistä
Crasman Studion rajapinta on toteutettu REST/JSON-muotoisena. API-kutsut tehdään SSL-suojatun HTTP-protokollan yli.
Rajapinta ei ole oletusarvoisesti auki, vaan rajapinnan käyttöönoton yhteydessä Crasmanille on ilmoitettava mistä verkoista (CIDR), tai mistä yksittäisistä IP-osoitteista API-kutsuja aiotaan tehdä. Crasmanille on myös ilmoitettava Studiossa olevista käyttäjätunnuksista, joilla halutaan StudioAPI:n kautta pystyä tunnistautumaan.
Kutsujen muoto
API-kutsut tehdään muodossa:
https://[asiakas].studio.crasman.fi/studioapi/v2/[toiminto]/:parametri1/:parametri2/:parametriN
Kaikiin kutsuihin (paitsi login) on liitettävä mukaan HTTP-otsikko: X-AuthToken: {auth token arvo} (saadaan login‐kutsusta).
Vastausten muoto
StudioAPI:n vastaukset ovat suurimmaksi osaksi UTF8-koodatussa JSON-muodossa. Poikkeuksena tähän ovat kutsut, jotka palauttavat binääridataa (tiedostoja).
JSON-vastauksen muoto
Avain | Selite | Lisätietoja |
status | Kutsun tila |
"ok": suorituksessa ei ollut virheitä, "error": kutsun suorituksessa tapahtui virhe |
code | Virhekoodi |
0: virhettä ei tapahtunut, muu arvo: kts. Virhetilanteet |
result | Kutsun vastaus |
Virhetilanteet
Virhetilanteissa kutsujen http-statuskoodi on 500 (muutoin 200) ja vastaus tulee tällöin aina JSON-muodossa. Virhetilanteen syystä saa käsityksen tutkimalla vastauksen code-arvoa.
Rajapintakutsut
Autentikointi
Resurssi | Kuvaus |
---|---|
POST login | Kirjautuu sisään, palauttaa authToken‐arvon |
GET logout | Kirjautuu ulos |
Kokoelmat
Resurssi | Kuvaus |
---|---|
DELETE collections/:collectionId/:fileId | Poistaa tiedoston kokoelmasta |
PUT collections/:collectionId/:fileId | Linkittää tiedoston kokoelmaan |
GET collections | Palauttaa kokoelmat |
Tiedostot
Resurssi | Kuvaus |
---|---|
GET files/:folderId/:limit/:offset | Listaa tiedostot kansiosta/kokoelmasta/jaetusta kansiosta |
GET file/:fileid/:conversionId | Lataa tiedoston tai tietyn konversion tiedostosta, HUOM: palauttaa raakadataa, ei JSON:ia |
GET filedetails/:fileId | Palauttaa tiedoston tiedot |
POST filedetails/:fileId | Päivittää tiedoston tietoja. |
POST upload/:folderId | Aloittaa upload-prosessin. Palauttaa uploadToken-arvon, jonka avulla tiedosto uploadataan. |
PUT upload/:folderId/:uploadToken | Lähettää osan tiedostoa Studioon (max 1MB paloissa) |
POST upload/:folderId/:uploadToken | Lopettaa upload-prosessin. Kutsun jälkeen Studio tarkistaa vastaanotetun tiedoston ja lisää sen kansioon. |
DELETE file/:fileId | Poistaa tiedoston |
POST search | Hakee tiedostoja hakuehdoin. Mahdollisuus käyttää yksittäisen metatietokannan kenttiä, tai tiedoston perustietoja ehtoina. |
POST quickshare/:fileId | Pikajakaa tiedoston sähköpostitse halutulle vastaanottajalle. |
POST movefile/:fileId/:folderId | Siirtää tiedoston toiseen kansioon. |
DELETE fileheader/:fileId/:headerName | Poistaa tietyn kustomoidun HTTP-headerin tiedostolta. |
PUT fileheader/:fileId/:headerName | Asettaa tietylle tiedostolle kustomoidun HTTP-headerin. |
GET fileheaders/:fileId | Palauttaa tiedostolle asetetut kustomoidut HTTP-headerit. |
DELETE comments/:commentId | Poista kommentti. |
POST replace/:fileId | Aloittaa replace-prosessin. Palauttaa uploadToken-arvon, jonka avulla tiedosto uploadataan. |
PUT replace/:fileId/:uploadToken | Lähettää osan tiedostoa Studioon (max 1MB paloissa) |
POST replace/:fileId/:uploadToken | Lopettaa replace-prosessin. Kutsun jälkeen Studio tarkistaa vastaanotetun tiedoston ja korvaa määritellyn tiedoston. |
GET filetags/:fileId | Palauttaa tiedostoon liitetyt tagit |
POST filetags/:fileId/:tagId | Lisää tagin tiedostoon. |
DELETE filetags/:fileId/:tagId | Poistaa tagin tiedostosta. |
PUT comments/:commentId/:comment | Päivitä kommentti. |
POST comments/:type/:id/:comment | Lisää kommentti resurssiin. |
GET conversions | Palauttaa kustomoidut kuvakonversiomääritykset |
GET comments/:type/:Id | Palauttaa resurssiin liittyvät komentit. |
Kansiot
Resurssi | Kuvaus |
---|---|
GET folder/:folderId | Palauttaa yksittäisen kansion perustiedot |
GET folder/:folderId/perms/:perm | Tarkistaa yksittäisen kansion oikeusmäärityksiä. |
GET folders/:parentId | Listaa kansiot tietyn kansion alta. Jos parentId:tä ei anneta, listataan päätason kansiot. |
POST folders/:parentId | Luo uuden kansion parametrina annetun kansion alle, palauttaa luodun kansion id:n. |
GET foldersettings/:folderId | Palauttaa kansiolle asetettuja asetuksia. |
POST foldersettings/:folderId | Asettaa kansion asetuksia. |
DELETE folders/:folderId | Poistaa kansion. |
GET allfolders/:limit/:offset | Listaa Studion kaikki kansiot |
Muut
Resurssi | Kuvaus |
---|---|
PUT /apisettings/:setting/:value | Asettaa istuntokohtaisia asetuksia |
PUT /apisettings/reset | Palauttaa istuntokohtaiset asetukset alkutilaan |
GET ping | Testaa StudioAPI-yhteyden toimivuutta. |
GET metadatafields | Palauttaa kustomoitujen metadatakenttien tiedot |
Julkiset kansiot
Resurssi | Kuvaus |
---|---|
DELETE publicfolders/:publicFolderId/:fileId | Poistaa tiedoston jaetusta kansiosta |
PUT publicfolders/:publicFolderId/:fileId | Linkittää tiedoston jaettuun kansioon |
GET publicfolders/:parentId | Palauttaa jaetut kansiot päätasolta tai parametrina annetun pääkansion alta |
Haku
Resurssi | Kuvaus |
---|---|
GET dbsearch/:database/:language/:field/:operator/:value | Hakee tiedostoja liitettyjen tietokantojen perusteella |
POST filesearch | Hakee tiedostoja halutun kansion alta rekursiivisesti. |
Tagit
Resurssi | Kuvaus |
---|---|
POST tags | Lisää uuden tagin. |
GET tags | Listaa kaikki tagit |
DELETE tags/:tagId | Poistaa tagin. |
Virhekoodit
Virhekoodi | Selite | |
-1 | UNDEFINED | Määrittelemätön virhetilanne |
0 | OK | Ei virhettä |
1 | INVALID_AUTHENTICATION | Virheellinen käyttäjätunnus tai salasana |
2 | MISSING_PARAM | API-kutsu oli puutteellinen |
3 | UNSUPPORTED_API_VERSION | API-versio ei ole tuettu |
4 | UNAUTHORIZED_NETWORK | Käytetty verkko ei ole sallittu |
5 | STUDIO_API_NOT_ENABLED | StudioAPI:a ei ole kytketty asiakkaalle käyttöön |
6 | USER_NOT_ALLOWED | Käyttäjä ei ole sallittu StudioAPI:n käyttöön |
7 | PARENT_FOLDER_NOT_EXISTS | Kutsussa käytettyä pääkansiota ei löytynyt tai saatu avattua |
8 | NO_PERMISSIONS | Käyttöoikeusvirhe |
9 | FATAL | Määrittämätön Studion sisäinen virhetilanne |
10 | AUTHENTICATION_ERROR | Kirjautumisessa tapahtunut määrittämätön virhe |
11 | FOLDER_NOT_EXISTS | Kutsussa käytettyä kohdekansiota ei löytynyt |
12 | UPLOAD_TOKEN | Tiedoston lähetyksessä käytetty uploadToken-avain oli virheellinen |
13 | INVALID_ACTION | Virheellinen StudioAPI-kutsu |
14 | FILE_NOT_EXISTS | Kutsussa käytettävää tiedostoa ei löytynyt |
15 | INVALID_PARAM | Virheellinen parametri kutsussa |
17 | AUTH_TOKEN_MISSING | AuthToken-avain puuttuu kutsusta |
18 | SESSION_NOT_FOUND | Istuntoa ei löytynyt annetulla AuthToken-avaimella |