Compatibiliteit

Wat wij in v1 zonder aankondiging mogen wijzigen, en wat een nieuwe hoofdversie zou vergen. Opgeschreven als opsomming in plaats van als belofte, zodat een koppeling zich precies tegen de juiste verzameling kan wapenen.

Paden, methoden, scopes, veldnamen en foutcodes staan in het Engels, want Engels is de taal van de koppeling zelf — het is wat een aanroeper typt of vergelijkt. Dat geldt ook voor elk codevoorbeeld, elke JSON-payload en de exacte zin die een foutantwoord meedraagt: /v1 leest Accept-Language niet, en een vertaling van wat de API werkelijk stuurt zou die verkeerd beschrijven. Alles wat erover geschreven staat, volgt de taal van deze pagina.

De huidige revisie is 2026-08-01. Het pad blijft /v1; de revisie benoemt het document dat het beschrijft.

Wijzigingen die wij niet in v1 doorvoeren

Deze vergen een nieuwe hoofdversie. Mocht die ooit nodig zijn, dan blijven bestaande versies antwoorden zolang de migratie loopt.

Een bewerking verwijderen.
Een parameter of een veld in een antwoord verwijderen of hernoemen.
Een nieuwe verplichte parameter toevoegen.
Een tot dan toe optionele parameter verplicht maken.
Het type van een parameter of van een antwoordveld wijzigen.
Een waarde uit een enum verwijderen.Een client die op de waarde vertakt, heeft geen tak voor het geval dat die ontbreekt, en faalt dus op de manier waarop zijn taal faalt bij een onafgevangen geval.
Een nieuwe validatieregel aan een bestaande parameter toevoegen.Een verzoek dat gisteren nog slaagde, gaat mislukken — dat is functionaliteit die wegvalt, vermomd als een bugfix.
De eisen voor authenticatie of autorisatie wijzigen, inclusief de scope die een bewerking verlangt.

Wijzigingen die wij op elk moment kunnen doorvoeren

Uw koppeling moet ze allemaal verdragen. Ze zullen gebeuren, en ze worden niet aangekondigd.

Een nieuwe bewerking toevoegen.
Een nieuwe optionele parameter toevoegen.
Een nieuwe optionele verzoekheader toevoegen.
Een nieuw veld aan een antwoord toevoegen.Lees antwoorden soepel in — een client die onbekende velden weigert, breekt op de eerste toevoeging die wij doen.
Een nieuwe antwoordheader toevoegen.
Een waarde aan een enum toevoegen.Behandel een onbekende waarde als standaardgeval en niet als fout. Er komen nieuwe paspoortcategorieën en nieuwe gebeurtenistypen bij.
Een foutcode opsplitsen in preciezere codes — maar alleen waar de oorspronkelijke code niet al door logica tijdens de uitvoering, zoals een nieuwe poging, kon worden opgelost.Een code opsplitsen waarop een client VERTAKT breekt die client; een code opsplitsen die hij alleen logt niet. Het verschil zit erin of het gedrag ervan afhing.

Wat uw client moet verdragen

Elk van deze punten hoort bij een wijziging hierboven die wij ons voorbehouden. Een client die er één schendt, breekt op iets wat wij als routine beschouwen.

Negeer velden in een antwoord die u niet kent, in plaats van het antwoord te weigeren.
Behandel een onbekende enumwaarde als standaardgeval, niet als fout.
Behandel identificaties als ondoorzichtige tekenreeksen; ontleed ze nooit en zoek er geen patronen in.
Vertrouw niet op de VOLGORDE van velden in een JSON-object, en evenmin op de exacte formulering van een leesbare foutmelding. Vertak in plaats daarvan op de machineleesbare foutcode.
Probeer het opnieuw bij een 429 en bij elke andere weigering die een Retry-After-header draagt, en wacht de tijd af die daarin staat. De header hoort niet alleen bij een 429: ook een 409 resource_busy, een 503 storage_unavailable en een 503 entitlement_unavailable dragen hem, omdat opnieuw proberen daar de oplossing is.
Probeer een 5xx opnieuw met een NIEUWE Idempotency-Key. Een sleutel waarop een serverfout is vastgelegd, speelt die fout de hele bewaartermijn opnieuw af — met opzet, want de mislukking kan een verloren antwoord zijn geweest op een schrijfactie die WEL is geslaagd, en juist het hergebruiken van de sleutel voorkomt dat één mislukte schrijfactie er twee worden.
Let op de Deprecation- en Sunset-antwoordheaders en op de Link: rel="successor-version" die zij meedragen. Zo wordt het verdwijnen van een endpoint aangekondigd, en die aankondiging komt ruim voordat het endpoint ophoudt te antwoorden.

Behandel elke identificatie als een ondoorzichtige tekenreeks van maximaal 255 tekens. Ontleed ze niet, controleer hun formaat niet en ga er niet van uit dat het UUID's zijn — het formaat kan zonder aankondiging veranderen.

Uitfasering

Een endpoint dat verdwijnen gaat antwoordt met Deprecation- en Sunset-headers en met een Link-header die de opvolger noemt. Ze komen ruim voordat het endpoint ophoudt te antwoorden. Let erop.