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