Abonneren op de API Changelog

Volgen

De API en het beleid ten aanzien van de API worden regelmatig aangepast. Daarom is het van groot belang om je te abonneren op de changelog. Hierdoor blijf je als koppelpartij altijd op de hoogte van wijzigingen. Dit doe je door te klikken op ''volgen'' en daarna te kiezen voor ''nieuwe artikelen''.

Deze wijzigingen zijn onderhevig aan de volgende richtlijnen, die gelden voor het wijzigingsbeleid van deze API:

  • Loket.nl kan soms zonder voorafgaande kennisgeving wijzigingen aanbrengen in de API en het beleid.
  • Loket.nl zal proberen gebruikers vooraf op de hoogte te stellen van eventuele (baanbrekende) wijzigingen m.b.t. de API.
  • Loket.nl is niet aansprakelijk jegens u of een derde partij voor dergelijke wijzigingen of eventuele nadelige gevolgen van dergelijke wijzigingen.
  • Loket.nl zal proberen om baanbrekende wijzigingen zoveel mogelijk te voorkomen.

Meldingsperiodes
Met betrekking tot wijzigingen zal Loket.nl ernaar streven de volgende meldingstermijnen per type wijziging in acht te nemen. Door onze versioneringsstrategie op resource niveau heeft deze API de mogelijkheid om meerdere versies van dezelfde resource in één keer te draaien. Dit maakt een venster mogelijk waarin zowel de oude als de nieuwe versie beschikbaar zijn. Dit maakt een geleidelijke overgang naar de nieuwe versie mogelijk.

 

Type wijziging

Meldingsperiode

Supportperiode oude versie

Niet baanbrekende verandering

2 weken

Geen nieuwe versie

Baanbrekende verandering

2 weken

6 maanden

Kritiek

Door de aard van de veranderingen is het mogelijk dat we niet de normale procedure m.b.t. verandermanagement kunnen volgen.

Dit hang af van de ernst van de issue

 

We definiëren een niet-baanbrekende verandering als volgt. Elke wijziging aan de API die geen storingen veroorzaakt in de applicaties die de API aanroept.

- Introductie van een nieuw optioneel veld in een bestaande resource

- Invoering van een nieuw endpoint

- Invoering van een nieuwe operatie (GET/PUT/POST/PATCH/DELETE)

- Introductie van een nieuwe optionele parameter op een endpoint

- Introductie van een nieuwe versie voor een resource


We definiëren een baanbrekende verandering als volgt. Elke verandering aan een API die mogelijk storingen kan veroorzaken in de applicaties die de API aanroept.

- Het wijzigen van een bestaand JSON-element (naam, datatype, patroon, min/max lengte, enz.)

- Verwijderen van een JSON-element, endpoint, operation of parameter

- Introductie van een vereist JSON-element

- Invoeren van een vereiste parameter op een endpoint

- Het passeren van de obsoleteDate van een versie voor een resource

Versiebeheer
De Loket API maakt gebruik van twee soorten versioning. API versioning en resource versioning.

API-versiebeheer
API-versiebeheer gebeurt via het pad waar na de domein-URL (api.loket.nl) het pad begint met de API-versie. De huidige versie van de API is V2. API-versie zal naar verwachting zelden veranderen, omdat de meeste problemen opgelost kunnen worden door middel van resource-versiebeheer.

Resource-versiebeheer
Elke JSON-bron in de API wordt via de accept header weergegeven. Hiermee kunnen gebruikers van de API-invloed uitoefenen op welke versie wordt geretourneerd door de verplichte accept header in te stellen. De accept header van de aanvraag moet een waarde hebben zoals application/json;version=2018-01-01.

Hier wordt het tweede deel van de header gebruikt om te verwijzen naar een specifieke versie van de resource (2018-01-01). Bij het aanroepen van de API is het mogelijk om andere data aan te leveren in plaats van de exacte resources versie(s). De businesslogic zal de versie selecteren die AAN of VOOR de opgegeven datum is.

Bijvoorbeeld: laten we zeggen dat er twee versies van een resource zijn. Dit zijn 01-01-2018 en 01-09-2018. Bij het aanroepen van de API lever je applicatie/json;version=2018-08-01, in dat geval zal de API de versie 2018-01-01 gebruiken als de dichtstbijzijnde versie in het verleden.

Een respons geeft aan welke resourceVersion werd gebruikt en de ' obsoleteDate ' van die versie (in de meeste gevallen is dit nul). De 'obsoleteDate' geeft aan wanneer de resourceVersion niet meer beschikbaar zal zijn via de API. Met de introductie van een nieuwe versie van een resource wordt de 'obsoleteDate' voor de oude versie ingesteld op 6 maanden na de introductie van de nieuwe resource. De gebruiker krijgt hiermee 6 maanden de tijd om de wijziging in te voeren. Als dit niet gebeurt, zal dit waarschijnlijk leiden tot een mislukking van de implementatie.

In deze developer portal kunt u de servicecontracten vinden voor elke actieve versie van een resource. Als er meerdere versies van een resource zijn, kunt u het bijbehorende schema bij die resource selecteren.

Changelog
De changelog voor deze API is hier te vinden. Abonneer je door op ''volgen'' te klikken en vervolgens te kiezen voor ''nieuwe artikelen''.

Voorbeeld van een changelog:

mceclip0.png

Was dit artikel nuttig?
Aantal gebruikers dat dit nuttig vond: 0 van 0