Versiebeheer

Elk endpoint antwoordt op twee paden:

POST /api/v1/payments/create     versioned, use this
POST /api/payments/create        unversioned, permanently supported

Beide draaien vandaag identieke code.

Gebruik het pad met versie. Het is de enige manier om zeker te weten dat een toekomstige wijziging u niet bereikt. Een integratie op het pad zonder versie krijgt wat “zonder versie” op dat moment betekent. Vandaag is dat v1, en ooit is dat misschien niet meer zo.

Het pad zonder versie is een permanente alias, geen deprecation. Het wordt niet verwijderd. Er bestaan integraties die niet kunnen worden bijgewerkt, zoals plugins die merchants in hun eigen tempo of nooit upgraden, en die moeten blijven werken.

Elke response vertelt u welke versie hem heeft afgehandeld:

X-API-Version: v1

GET /api/versions toont wat er bestaat en naar welke versie uw request is omgezet.

Wat telt als een breaking change

We kondigen breaking changes van tevoren aan. Die belofte betekent alleen iets als we het eens zijn over wat dat woord betekent.

Zonder aankondiging doorgevoerd, in de huidige versie:

een nieuw endpoint
een nieuw optioneel requestveld
een nieuw responseveld
een nieuwe enumwaarde die clients geacht worden te tolereren
een validatieregel die is versoepeld om meer invoer te accepteren
een correctie van een response die nooit overeenkwam met het gedocumenteerde gedrag
elke wijziging zonder zichtbaar effect op requests of responses

Vereist een nieuwe versie:

een request- of responseveld verwijderen of hernoemen
het type of de betekenis van een veld wijzigen
de statuscode voor een bestaande uitkomst wijzigen
een optioneel veld verplicht maken
validatie aanscherpen zodat eerder geaccepteerde invoer wordt geweigerd
een endpoint verwijderen of het pad ervan wijzigen
wijzigen wat er gebeurt als een veld wordt weggelaten

De onderliggende regel: als een integratie die vandaag werkt zou stoppen met werken, of zich anders zou gaan gedragen zonder dat de eigen code verandert, dan is het een breaking change.