REST API v1 vs v2

Opgelet: de REST API versie 1 werd uitgefaseerd en is vanaf 1 juni ‘23 niet meer ondersteund!

MediaHaven biedt sinds het begin een REST API aan om bewerkingen uit te kunnen voeren op mediaobjecten. Vanaf MediaHaven versie 21.1 (uitgebracht op 16 april 2021) werd van deze REST API een nieuwe versie uitgerold. We zullen verder in de tekst deze twee versies van elkaar onderscheiden met de aanduidingen “v1” en “v2”.

Hoewel veel van de basisfuncties in de nieuwe REST API (zoals het opvragen van een resource, het uitvoeren van een zoekopdracht,…) quasi onveranderd zijn gebleven, werden er ook wijzigingen ingevoerd die backwards incompatible zijn. Hierdoor zouden bestaande integraties die gebruik maken van de REST API v1 kunnen breken wanneer ze naar het nieuwe endpoint worden overgezet.

De oude REST API v1, op het huidige endpoint, wordt nog ondersteund tot MediaHaven versie 22.1, maar we raden sterk aan om naar de nieuwe REST API v2, op het nieuwe endpoint, over te stappen.

Endpoints

Zeticon koos voor het versiebeheer van hun REST API voor versiebeheer via het URL-pad. Dit betekent dat het versienummer toegevoegd wordt aan het URL-pad om de v2 van de REST API te bereiken. Concreet:

Note: Dit zijn de endpoints voor de productieomgeving! Voor een beschrijving van de verschillende omgevingen en hun endpoints, zie Alles om te starten met het bouwen van een integratie.

Verschillen tussen REST API v1 en v2

Hieronder lijsten we eerst kort de belangrijkste backwards incompatible verschillen op tussen de REST API v1 en v2. Daarna gaan we dieper in op wat dat concreet inhoudt.

• authenticatie kan énkel nog via OAuth2: Basic Auth wordt niet meer ondersteund
• de structuur van de JSON response wijzigt
• de resource /media is nu /records geworden

Voor een volledig overzicht van de verschillen verwijzen we je naar de links onderaan deze pagina.

Authenticatie

• Authenticatie is het proces waarbij gebruikers aantonen dat ze werkelijk zijn wie ze beweren te zijn, of liever: dat ze de werkelijke eigenaar zijn van de identiteit die ze beweren te hebben.
• Autorisatie is het proces waarbij een applicatie, op basis van de vastgestelde en geverifieerde identiteit, bepaalde acties toelaat of net weigert.

De REST API v1 liet twee manieren van authenticatie toe:

• basic authentication
• OAuth2

Basic authentication is een heel simpele vorm van authenticatie die deel uitmaakt van het HTTP-protocol. Hierbij worden gebruikersnaam en wachtwoord met elke call naar de API meegegeven in de HTTP Authorization header met de Basic prefix, bijvoorbeeld:

Authorization: Basic ZGVtbzpwQDU1dzByZA==

OAuth2 daarentegen is een “autorisatie framework”, een standaard op zich naast het HTTP-protocol. Hierbij wordt gebruik gemaakt van access tokens met een korte levensduur. Ook deze worden − gewoonlijk − meegegeven in de HTTP-requests via de Authorization header maar met de Bearer prefix, bijvoorbeeld:

Authorization: Bearer RsT5OjbzRn430zqMLgV3Ia

Op deze pagina vind je meer informatie over de OAuth2 authenticatie: Alles om te starten met het bouwen van een integratie.

Waarom is dit belangrijk? Integraties gebaseerd op REST API v1 zullen niet meer werken aangezien ze niet meer geauthenticeerd zijn.

Responseformaten

In REST API v1 was het al mogelijk om de nieuwe responseformaten (zowel voor JSON als voor XML) te verkrijgen via content negotiation in de HTTP Accept header. In de REST API v1 waren volgende responseformaten mogelijk:

De nieuwere responseformaten in de REST API v1 (in de tabel hierboven: JSON v2 en XML v2) worden de standaard in de REST API v2. Dit betekent dat de Accept headers application/vnd.mediahaven.v2+json en application/vnd.mediahaven.v2+xml komen te vervallen. Het standaardformaat van de response in de REST API v2 is nu quasi gelijk aan het v2 formaat in de REST API v1.

Naast een wijziging aan de structuur (i.e. op welk JSON-pad bepaalde data te vinden is) van de response, is ook de casing gewijzigd:

• de JSON keys in het v1 formaat zijn camelCase (e.g., totalNrOfResults)
• de JSON keys in het v2 formaat zijn PascalCase (e.g., TotalNrOfResults)

Voorbeelden

• JSON responseformaat application/json in REST API v1

{
    "totalNrOfResults": 10,
    "startIndex": 0,
    "mediaDataList": [
        {
        ...
        }
    ]
}

• JSON responseformaat application/vnd.mediahaven.v2+json in REST API v1

{
    "TotalNrOfResults": 10,
    "StartIndex": 0,
    "MediaDataList": [
        {
        ...
        }
      ]
}

• JSON responseformaat application/json in REST API v2

{
    "NrOfResults" : 5
    "TotalNrOfResults": 10,
    "StartIndex": 0,
    "Results": [
        {
        ...
        }
    ]
}

Zo zien we hier ook dat de array die de resultaten bevat in de REST API v2 nu altijd Results is.

Waarom is dit belangrijk? Integraties zijn meestal hoofdlettergevoelig en verwachten bepaalde data op een bepaalde plaats te vinden, deze assumpties zouden niet meer gelden in de REST API v2.

Van /media resource naar /records

De belangrijkste resource, de mediaobjecten, heetten in de REST API v1 media. Dit is nu gewijzigd naar records.

Nieuwe features

Zie MediaHaven Customer Support > REST API > Rest V2 vs v1 changes > New-features

Links

Documentatie

De documentatie van beide versies is hier te vinden:

• REST API v1: https://archief.viaa.be/mediahaven-rest-api
• REST API v2: https://archief.viaa.be/mediahaven-rest-api/v2/api-docs/index.html

Raadpleeg hier de MediaHaven-documentatie over de verschillen tussen REST API v1 en v2:

• MediaHaven Customer Support > REST API > Rest V2 vs v1 changes