Versies en compatibiliteit

De API heeft één hoofdversie, /v1, en die groeit alleen. Een integratie die je vandaag schrijft, blijft werken terwijl er nieuwe functies bij komen: niets waarop ze steunt, krijgt een andere naam, verdwijnt of krijgt een nieuwe betekenis.

Het versienummer

De API heeft een versienummer zoals 1.62.0. Het verandert bij elke release:

• het minor-nummer als er iets bij komt: een endpoint, een veld, een event;
• het patch-nummer als een beschrijving of de tekst van een melding wordt gecorrigeerd en verder niets verandert.

Je kunt op elk moment lezen welke versie een adres levert:

GET /v1/health heeft ook een version, maar dat is de versie van de release van Sursa die het adres bedient, niet de versie van de API.

Je kiest geen minor-versie: elk request wordt door de huidige versie afgehandeld. Dankzij de regels hieronder is dat veilig.

Wat er in /v1 kan veranderen

Deze wijzigingen kunnen in elke minor-versie komen. Schrijf je integratie zo dat ze er niet door breekt:

• Nieuwe endpoints.
• Nieuwe optionele parameters en velden in requests. Requests zonder die velden werken zoals voorheen.
• Nieuwe velden in responses, objecten en events.
• Nieuwe enumwaarden in responses, zoals een nieuwe status van een kaart of een nieuw eventtype.
• Nieuwe foutcodes en nieuwe responseheaders.
• Limieten die minder streng worden: een grotere maximale lengte, een ruimer bereik.
• Anders geformuleerde message-teksten van fouten en anders geformuleerde beschrijvingen.

Wat je code moet verdragen

• Negeer velden die je niet kent. Faal niet als een response meer velden heeft dan je verwacht, en gebruik geen strikte schema’s die ze afwijzen.
• Accepteer enumwaarden die je niet kent. Elke enumeratie in een response kan groeien. Behandel een onbekende waarde als “overig” en niet als een fout.
• Sla eventtypes over die je niet kent, zowel in webhooks als in streams.
• Behandel onbekende foutcodes op basis van hun HTTP-status: zie Fouten.
• Ga niet uit van de volgorde van velden in JSON-objecten of van de exacte tekst van meldingen.

Wat in /v1 nooit verandert

• Een pad, parameter, veld of enumwaarde krijgt nooit een andere naam en wordt nooit verwijderd.
• Het type van een veld verandert nooit, en een veld krijgt nooit een nieuwe betekenis, zoals nieuwe eenheden.
• Een request dat vandaag wordt geaccepteerd, wordt later niet geweigerd.
• De statuscode van een geslaagde response blijft hetzelfde.
• Foutcodes houden hun betekenis, en het veld detail van foutresponses houdt zijn vorm.
• Eventtypes krijgen nooit een andere naam en worden nooit verwijderd, en hun data krijgt er alleen velden bij.

Brekende wijzigingen

Is er ooit een incompatibele wijziging nodig, dan verschijnt die als nieuwe hoofdversie, zoals /v2, naast /v1. /v1 blijft ongewijzigd werken, en de twee draaien naast elkaar.

Wanneer een route wordt uitgefaseerd:

1. Hij wordt in de specificatie gemarkeerd als deprecated en in het wijzigingslogboek vermeld met de datum waarop hij wordt uitgeschakeld.
2. Zijn responses bevatten de headers Deprecation: true en Sunset: <date>.
3. Hij blijft na de aankondiging nog minstens 180 dagen werken. Organisaties waarvan de API-sleutels hem gebruiken, krijgen dat minstens 90 dagen van tevoren schriftelijk te horen.
4. Na de einddatum antwoordt hij nog 90 dagen met 410 en de code api.gone.

Let in je logs of monitoring op de header Deprecation: dat is het vroegste signaal dat een route die je gebruikt, gaat verdwijnen.

Op de hoogte blijven

Het wijzigingslogboek van dit portaal vermeldt elke release met wat er is toegevoegd en wat als verouderd is gemarkeerd. Vergelijk de code van je integratie, voordat je hem bijwerkt, met de items sinds de versie waarvoor je hem hebt gebouwd.