API - úvod

Obecné

Každý portál má své separátní nastavení přístupu a každý portál má svůj vlastní end-point pro volání API.

Popis API se nachází na adrese: {PortalURL}/swagger - tedy například https://medicalmedia.cuni.fenomio.stream/swagger

URL jednotlivých api volání napoví popis na /swagger adrese. Většinou se pracuje s entitou media a jejími relacemi. To je na adrese {PortalUrl}/api/v1/media...

Data se předávají v JSON. Názvy vlastností jsou v PascalCase, tedy například Name, MediaTypeId, OwnerUserId. Na vstupu server nerozlišuje velikost prvního znaku, v odpovědích ale vždy dostanete PascalCase.

Zabezpečení

API je zabezpečeno standardním Bearer tokenem v hlavičce každého requestu. https://swagger.io/docs/specification/authentication/bearer-authentication/
Tedy název hlavičky je "Authorization" a její hodnota "Bearer APITOKEN", kde APITOKEN je token vygenerovaný v administraci platformy u příslušného portálu.

Token je vázaný na konkrétní portál. Volání s tokenem jednoho portálu na adrese jiného portálu skončí chybou 401 a přes API se nedostanete k datům jiného portálu.

  • Tip: Ve Swagger dokumentaci najdete tlačítko "Authorize". Po vložení hodnoty Bearer APITOKEN začne Swagger token přikládat ke každému požadavku, takže si všechna volání vyzkoušíte přímo z dokumentace.
  • Tip: Pro jednodušší testování na webu jsme implementovali výjimku - pokud v requestu hlavička "Authorization" chybí, autorizace se úspěšně provede, pokud je ve stejném webovém prohlížeči přihlášen uživatel s rolí Administrátor daného portálu.

Chybové odpovědi

Všechny chyby mají jednotný tvar - JSON objekt s jedinou vlastností Message:

{ "Message": "Owner user was not found." }

Platí to i pro chyby validace vstupu a pro neočekávané chyby serveru. Použité stavové kódy:

  • 400 - vstup není platný, nebo požadovaná operace v daném stavu nelze provést
  • 401 - token chybí, není platný, je zakázaný nebo mu vypršela platnost
  • 404 - entita nebyla nalezena (smazané entity se nevrací)

Zakládání a úprava média

Při zakládání média přes API stačí vyplnit Name, MediaTypeId (10 = video, 20 = audio) a OwnerUserId. Nevyplněná pole se doplní výchozími hodnotami portálu - včetně výchozí licence a zapnutého ukládání originálního souboru.

Média zakládaná přes API obcházejí schvalovací workflow a jsou rovnou označena jako schválená. Na portálech se zapnutým schvalováním publikování tedy není potřeba nic dalšího potvrzovat.

Playlist je také médium, ale zakládá se vlastním endpointem /api/v1/playlist, ne přes /api/v1/media.

Částečná úprava (PUT)

Metoda PUT podporuje částečnou úpravu - co v těle nepošlete, to se nezmění. Nemusíte tedy nejdřív číst celé médium, měnit jednu hodnotu a posílat zpět všechno.

  • texty, datumy, příznaky, souřadnice, složka a jazyk: null nebo vynechání znamená "neměnit"
  • MediaAccessLevelId a MediaLicenseId: 0 nebo vynechání znamená "neměnit"
  • explicitní 0 u MediaFolderId, SpokenAudioLanguageId, Lat a Lon hodnotu naopak zruší

Požadavek { "Name": "Nový název" } tedy změní jen název a ostatních třicet vlastností média nechá být.

Práci s médii - hledání, detail, vytvoření, úprava, smazání

  • /api/v1/media (GET)
  • /api/v1/media/{mediaId} (GET) - detail jednoho média
  • /api/v1/media (POST)
  • /api/v1/media/{mediaId} (PUT)
  • /api/v1/media/{mediaId} (DELETE)

Hledání v seznamu médií nabízí kromě filtrů podle typu, stavu, složky a vlastníka i parametr SearchedTextValueType, kterým určíte, ve kterém poli se hledá text ze SearchedText. Hodnota 110 hledá podle Id, 120 podle Guid, 30 podle názvu, 50 podle autora. Bez uvedení se hledá fulltextem. Velikost stránky je omezena na 250 záznamů; pokud si vyžádáte více, server ji srazí a skutečně použitou hodnotu vrátí v ItemsPerPage.

Nahrání zdrojového souboru a spuštění kódování

Soubor se nahrává k již existujícímu médiu po částech, ve třech krocích. Kódování se rozjede teprve posledním z nich.

  • /api/v1/media/{mediaId}/UploadInit (POST) - vrátí UploadUid a povolenou velikost chunku
  • /api/v1/media/{mediaId}/UploadChunk (POST) - opakovaně, jeden chunk za druhým
  • /api/v1/media/{mediaId}/UploadComplete (POST) - předá médium kódování

Poznámky k uploadu:

  • Médium musí být ve stavu kódování New. Do rozjetého nebo hotového kódování nahrávat nelze.
  • Přípona souboru musí odpovídat typu, se kterým bylo médium založeno. Nahrání zvukového souboru k médiu typu video skončí chybou 400.
  • UploadChunk posílá surová binární data - tělem požadavku jsou přímo bajty a Content-Type je application/octet-stream. UploadUid a číslo chunku se předávají v query parametrech. Ostatní dva kroky jsou běžný JSON.
  • Chunky je nutné posílat sekvenčně, ne paralelně - připojují se v došlém pořadí. Chunk s indexem 0 zahodí rozpracovaný soubor, takže přerušený upload lze začít znovu od začátku.
  • Velikost jednoho chunku je 3 MB. Větší chunk server odmítne a rozpracovaný soubor nechá nedotčený.
  • V UploadComplete lze volitelně zadat šablonu popisných dat a šablonu publikování. Pozor: šablona popisných dat přepíše název, popis, autora i licenci média.

Pokud zdrojový soubor už leží v cloudovém úložišti, upload není potřeba a stačí na něj ukázat:

  • /api/v1/media/{mediaId}/EncodeFileSourceFromCloud (POST)

Práce se zatříděním média:

  • /api/v1/media/{mediaId}/AddMediaCriteriaValue (POST)
  • /api/v1/media/{mediaId}/RemoveMediaCriteriaValue (POST)
  • /api/v1/media/{mediaId}/AssignedMediaCriteriaValues (GET)

Práce s tagy:

  • /api/v1/media/{mediaId}/AddMediaTag (POST)
  • /api/v1/media/{mediaId}/RemoveMediaTag (POST)
  • /api/v1/media/{mediaId}/AssignedMediaTags (GET)

Tagy se přiřazují podle názvu, ne podle Id. Pokud tag na portálu ještě neexistuje, přiřazením se rovnou vytvoří - stejně jako při zadání tagu v editoru. Odebrání ruší jen vazbu na médium, samotný tag na portálu zůstává.

Práce s vlastními tagy:

  • /api/v1/media/{mediaId}/AddMediaCustomTag (POST)
  • /api/v1/media/{mediaId}/RemoveMediaCustomTag (POST)
  • /api/v1/media/{mediaId}/AssignedMediaCustomTags (GET)

Aplikace šablon:

  • /api/v1/media/{mediaId}/ApplyMediaDataTemplate (POST)
  • /api/v1/media/{mediaId}/ApplyMediaSecurityTemplate (POST)

Šablona popisných dat přepíše název, popis, autora, poznámku, licenci a tagy. Šablona publikování a zabezpečení přepíše pouze ty hodnoty, které jsou v ní k aplikaci označené.

Práce se zařazením organizací média:

  • /api/v1/media/{mediaId}/AddOrganization (POST)
  • /api/v1/media/{mediaId}/RemoveOrganization (POST)
  • /api/v1/media/{mediaId}/AssignedOrganizations (GET)

Práce s přiřazením rozsahů povolených IP adres:

  • /api/v1/media/{mediaId}/AddMediaIpList (POST)
  • /api/v1/media/{mediaId}/RemoveMediaIpList (POST)
  • /api/v1/media/{mediaId}/AssignedMediaIpLists (GET)

Práce s přiřazením seznamů uživatelů:

  • /api/v1/media/{mediaId}/AddMediaUserList (POST)
  • /api/v1/media/{mediaId}/RemoveMediaUserList (POST)
  • /api/v1/media/{mediaId}/AssignedMediaUserLists (GET)

Práce s přiřazením externích serverů:

  • /api/v1/media/{mediaId}/AddEmbedPosition (POST)
  • /api/v1/media/{mediaId}/RemoveEmbedPosition (POST)
  • /api/v1/media/{mediaId}/AssignedEmbedPositions (GET)

Práce s kapitolami:

  • /api/v1/media/{mediaId}/AddMediaChapter (POST)
  • /api/v1/media/{mediaId}/RemoveMediaChapter (POST)
  • /api/v1/media/{mediaId}/MediaChapterList (GET)

Práce s titulky:

  • /api/v1/media/{mediaId}/AddMediaSubtitle (POST)
  • /api/v1/media/{mediaId}/RemoveMediaSubtitle (POST)
  • /api/v1/media/{mediaId}/MediaSubtitleList (GET)

Práce s přístupovými tokeny:

  • /api/v1/media/{mediaId}/AddMediaAccessToken (POST)
  • /api/v1/media/{mediaId}/RemoveMediaAccessToken (POST)
  • /api/v1/media/{mediaId}/MediaAccessTokenList (GET)

Práce s playlisty:

  • /api/v1/playlist (POST) - vytvoření playlistu
  • /api/v1/playlist/{playlistId} (PUT) - úprava playlistu
  • /api/v1/playlist/{playlistId}/AddMedia (POST)
  • /api/v1/playlist/{playlistId}/RemoveMedia (POST)
  • /api/v1/playlist/{playlistId}/MediaList (GET)

Playlist nelze vložit do playlistu. Playlist podporuje pouze úrovně ochrany soukromá (10), neveřejná (20) a veřejná (40) - úroveň chráněná (30) u playlistu není povolena, protože viditelnost se řídí obsaženými médii. Playlist je přehratelný, jakmile obsahuje alespoň jedno přehratelné médium.

Změny proti předchozí verzi API

Následující volání byla přejmenována nebo přesunuta:

  • /api/v1/media/{mediaId}/AvailableEmbedPositions → /api/v1/media/{mediaId}/AssignedEmbedPositions (vracelo přiřazené, ne dostupné pozice)
  • /api/v1/media/{mediaId}/AvailableMediaAccessToken → /api/v1/media/{mediaId}/MediaAccessTokenList
  • /api/v1/media/{mediaId}/AddMediaPlaylist → /api/v1/playlist/{playlistId}/AddMedia
  • /api/v1/media/{mediaId}/RemoveMediaFromPlaylist → /api/v1/playlist/{playlistId}/RemoveMedia
  • /api/v1/media/{mediaId}/MediaPlaylistList → /api/v1/playlist/{playlistId}/MediaList

Dále se změnilo:

  • Chyby validace vstupu vrací stejný tvar jako ostatní chyby, tedy objekt s vlastností Message. Dříve vracely odlišnou strukturu.
  • Metoda PUT nově podporuje částečnou úpravu. Dříve přepisovala všechny vlastnosti, takže požadavek s jednou hodnotou vynuloval zbytek.
  • Neplatné hodnoty úrovně ochrany, licence, složky a jazyka jsou odmítnuty chybou 400. Dříve se uložily.