Versies en einddatums¶
Elke aanroep gaat naar /api/v1. Dit voorvoegsel is de versie: zolang het antwoordt, blijft wat je
hebt gebouwd werken.
Wat er binnen een versie verandert¶
Binnen v1 komt er alleen iets bij: een nieuw optioneel veld in een verzoek, een nieuw veld in een
antwoord, een nieuwe route, een nieuwe waarde in een lijst die al meerdere waarden kon bevatten.
Schrijf je client zo dat een onbekend veld in een antwoord geen fout is, dan merk je hier niets van.
Een veld dat verdwijnt, een type dat smaller wordt, een optioneel veld dat verplicht wordt, een
andere statuscode of een route met een nieuwe naam: dat gebeurt nooit binnen v1. Zo'n wijziging
krijgt een eigen versie, /api/v2.
Hoe lang een versie blijft antwoorden¶
Komt /api/v2 er, dan blijft /api/v1 daarna nog twaalf maanden antwoorden. De einddatum staat
vast op de dag dat v2 verschijnt en schuift daarna niet meer op. Je hebt dus een volledig
begrotingsjaar om over te stappen, en je hoeft er niet naar te vragen: je leest hem zelf uit de
antwoorden die je toch al krijgt.
De twee headers¶
Zodra een einddatum bekend is, draagt elk antwoord onder /api/v1 twee headers — ook foutmeldingen,
juist omdat een aanroeper die alleen naar zijn eigen logs kijkt het anders mist:
Deprecation: @1790812800
Sunset: Fri, 01 Oct 2027 00:00:00 GMT
Deprecation is de dag waarop het einde is aangekondigd, als aantal seconden sinds 1 januari 1970
(RFC 9745). Sunset is de dag waarop de versie stopt
met antwoorden, als gewone HTTP-datum (RFC 8594).
Zie je deze headers niet, dan is er niets aangekondigd en is v1 gewoon actueel. Zie je ze wel,
controleer dan of je client ze logt of ergens laat zien; dat is de goedkoopste manier om zo'n datum
niet te missen.
Zien of het contract is veranderd¶
Het contract dat je installatie publiceert op /api/openapi.json
draagt twee waarden in het object info:
| Veld | Wat het je vertelt |
|---|---|
info.version |
de release van Core die je installatie draait, hetzelfde nummer als in de release notes. Draait een installatie een build van vóór de volgende release, zoals een testomgeving, dan staat er de release die die build gaat worden. Tot de eerste release staat er 0.1.0, en toevoegingen van voor die tijd veranderen dat niet. Een nieuwe release verandert het pad /api/v1 nooit |
info.x-contract-digest |
een SHA-256-vingerafdruk, in hex, van de routes en schema's in dat document. Hij verandert bij elke wijziging van het contract, ook tussen releases door, en blijft gelijk als er in het contract niets veranderde |
Genereer je een client uit het contract, bewaar dan de vingerafdruk van het document waaruit je hem genereerde. Wijkt de actuele vingerafdruk af, dan is het contract veranderd: genereer opnieuw en bekijk wat er is bijgekomen.
De statuscontroles horen bij geen enkele versie¶
/api/health en /api/ready staan buiten /api/v1. Ze dragen deze headers nooit en hun adres
verandert niet als er een nieuwe versie komt.