Inhoudstafel
Status: WIP
Ontwikkeling van een integratie
Introductie
Contentpartners (verder gewoon “CP” genoemd) kunnen zelf aan de slag met onze API’s en services om een integratie te bouwen. Hieronder vind je informatie om hier mee te kunnen starten.
We leggen uit wat de verschillende software-omgevingen zijn en waarvoor ze dienen gebruikt te worden, en, welke publieke API’s beschikbaar zijn en hoe daarmee te werken.
De verschillende omgevingen en hun endpoints
Meemoo heeft twee - publieke - omgevingen:
- QAS: of “staging”, een omgeving die productie nabootst en waarin ontwikkelaars en CP’s kunnen testen.
- PRD: of “production”, de werkelijke omgeving voor eindgebruikers.
De gewoonlijke (en sterk aangeraden) procedure is om eerst in de QAS-omgeving te testen en pas als alles naar behoren werkt en uitvoerig is getest, naar productie te gaan.
Netwerk locaties
Hieronder vind je de verschillende netwerk locaties eigen aan elke omgeving.
| QAS | PRD |
|---|---|
| archief-qas.viaa.be | archief.viaa.be |
Note: de transitie naar het meemoo-domein is nog niet volledig afgerond. Voorlopig is het beter en veiliger om nog het viaa-domein te gebruiken. Sowieso is het goed om bovenstaande netwerk locaties als omgevingsvariabelen (“environment variables”) te configureren in je applicatie of integratie. Op die manier kan er later triviaal geswitched worden naar het nieuwe domain.
Netwerk paden
Dit zijn de paden waarop de verschillende API’s bereikbaar zijn. Onderstaande paden, gecombineerd met de netwerk locaties van hierboven, geven je de volledige URL waarop de API kan worden aangesproken.
| Documentatie | Pad |
|---|---|
| OAI-PMH API | /mediahaven-oai/oai/ |
| MH REST API v1 | |
| MH REST API v2 | /mediahaven-rest-api/v2/ |
| IIIF 3.0 Image API | |
| Organizations API v2 |
Mediahaven API’s
Twee grote API’s zijn beschikbaar voor de content partners:
- REST API
- OAI-PMH API
Daar waar je via de REST API volledige CRUD-functionaliteit hebt (“Create, Read, Update, Delete”), is de OAI-PMH alleen-lezen. Anderzijds is een OAI-PMH API een welomlijnde standaard en is de REST API MediaHaven-specifiek.
REST API
Opgelet: de REST API versie 1 werd uitgefaseerd en is vanaf 1 juni ‘23 niet meer ondersteund!
De documentatie is hier te vinden:
Authenticatie voor de MediaHaven REST API v2
Authenticatie op v2 is uitsluitend mogelijk via OAuth 2.0! Basic Auth, zoals mogelijk was in de REST API v1, is nu niet meer ondersteund.
De referentie-documentatie voor OAuth 2.0 vind je hier: https://oauth.net/2/.
Voor de autorisatie zijn op de MediaHaven REST API v2 momenteel twee OAuth2 flows geïmplementeerd:
- “Authorization Code Grant Type”
- “Resource Owner Credentials Grant Type”
De keuze voor een flow hangt af van de use-case:
- user-facing web applicatie → “Authorization Code Grant Type”
- machine-to-machine applicatie integratie → “Resource Owner Credentials Grant Type”
(Zie bv A Guide To OAuth 2.0 Grants)
(De auth-flow die typisch gebruikt wordt voor machine-to-machine integraties is de “Client Credentials Grant Type”. Deze is echter - nog - niet geïmplementeerd in de MediaHaven REST API).
Om een applicatie via OAuth2 te laten authenticeren tegen MediaHaven, moet deze applicatie geregistreerd worden. We hebben dan van je nodig:
- Organisatienaam
- Naam van de integratie (of applicatie)
- Korte beschrijving van de integratie
- Destination server(s) (*)
- Redirect-URL (*)
(*) Enkel in het geval van de “Authorization Code Grant Type”.
Je krijgt dan een “client_id” en een “client_secret”. Om te authenticeren met deze client_id en client_secret, heb je een account nodig. Dat kan een persoonlijke account zijn of een “technische” account (bv. mediahaven.api@<org>.be)
OAI-PMH API
Zie https://developer.meemoo.be/docs/integratie/oai-pmh voor meer informatie.