Versies en uitfasering

De versie van de API staat in het adres: https://picked.nl/api/v1. Binnen v1 voegt Picked alleen toe. Waar je koppeling vandaag op bouwt, blijft werken.

Wat in v1 hetzelfde blijft

Binnen v1 verwijdert of hernoemt Picked geen endpoint, veld of foutcode, verandert het type of de betekenis van een veld niet, en maakt het geen optioneel veld verplicht. Elke wijziging wordt vóór de release getoetst aan de gepubliceerde specificatie van v1.

Wat erbij kan komen

Deze wijzigingen kunnen in v1 op elk moment komen, zonder aankondiging:

• een nieuw endpoint;
• een nieuw optioneel veld of nieuwe queryparameter in een verzoek;
• een nieuw veld in een antwoord;
• een nieuwe foutcode (code);
• een nieuwe header in een antwoord.

Bouw je koppeling daarom zo dat ze ermee overweg kan:

• Negeer velden die je niet kent. Laat je koppeling niet vastlopen op een onverwachte sleutel in een antwoord, en valideer antwoorden niet tegen een gesloten schema.
• Val terug op de HTTP-status als je een foutcode tegenkomt die je niet kent. Zie Foutmeldingen.
• Reken niet op de volgorde van de sleutels in een antwoord.

Uitfasering

Moet er in v1 iets verdwijnen of onverenigbaar veranderen, dan kondigt Picked dat minstens 12 maanden van tevoren aan, in de changelog. Het oude gedrag blijft die 12 maanden gewoon werken, zodat je de tijd hebt om over te stappen.

De specificatie

De volledige specificatie van v1 staat als OpenAPI op /docs/api.json en is te lezen op /docs/api (Engelstalig). Je kunt er een client mee genereren, of hem tussen releases vergelijken om precies te zien wat er veranderde.