Versiebeheer

De Avallo REST API gebruikt versiebeheer om wijzigingen voorspelbaar te maken en bestaande integraties te beschermen tegen onverwachte incompatibele wijzigingen.

Hoofdversie

De hoofdversie is onderdeel van de basis-URL:

https://api.avallo.nl/v1

Het onderdeel /v1 verwijst naar hoofdversie 1.

Een incompatibele wijziging aan het publieke contract vereist een nieuwe hoofdversie, bijvoorbeeld:

https://api.avallo.nl/v2

Volledige versie

Iedere door de API gegenereerde response bevat de header:

API-Version: 1.0.0

De waarde volgt:

MAJOR.MINOR.PATCH

Onderdeel	Betekenis
MAJOR	Incompatibele wijziging aan het publieke contract.
MINOR	Compatibele uitbreiding van het contract.
PATCH	Compatibele correctie zonder wijziging van het bedoelde contract.

De MAJOR-waarde komt overeen met de hoofdversie in de URL. Bij API-versie 1.2.3 blijft de basis-URL daarom /v1.

Compatibele wijzigingen

Binnen een bestaande hoofdversie kan Avallo compatibele uitbreidingen publiceren, zoals een nieuw endpoint, een optionele parameter of een aanvullend responseveld.

Clients moeten onbekende JSON-velden kunnen negeren. Een client mag niet afhankelijk zijn van de volgorde van JSON-velden of van niet-gedocumenteerd gedrag.

Verbeteringen aan documentatie en correcties waarmee de implementatie weer in overeenstemming wordt gebracht met het gepubliceerde contract gelden niet als incompatibele wijzigingen.

Incompatibele wijzigingen

Een wijziging is incompatibel wanneer een bestaande client zonder aanpassing niet langer correct kan functioneren.

Voorbeelden zijn het verwijderen of hernoemen van een endpoint of responseveld, het wijzigen van een datatype, het verplicht maken van een eerder optionele parameter of het wijzigen van de betekenis van bestaande gegevens.

Dergelijke wijzigingen worden niet binnen /v1 gepubliceerd.

Versie controleren

Gebruik --include om de responseheaders zichtbaar te maken:

curl --include --request GET \
  --url "https://api.avallo.nl/v1/groundwater-monitoring-wells" \
  --header "Accept: application/json" \
  --header "X-API-Key: {apiKey}"

Een response bevat onder andere:

HTTP/2 200
Content-Type: application/json
API-Version: 1.0.0

De URL bepaalt tegen welke hoofdversie de client communiceert. De API-Version-header vermeldt de exacte versie van het contract waarmee de response is gegenereerd.

Wijzigingsoverzicht

Wijzigingen worden gepubliceerd in de Changelog.

Daarin staat per versie welke functionaliteit is toegevoegd, gewijzigd, verouderd of verwijderd.

Uitfasering

Wanneer Avallo een hoofdversie uitfaseert, worden de betrokken afnemers vooraf geïnformeerd over de vervangende versie en de benodigde migratie.

Een bestaande hoofdversie wordt niet zonder voorafgaande communicatie buiten gebruik gesteld.