Discussie die al heel lang loopt terwijl de behoefte ernaar groeit, zeker als het gaat om publicatie in het API register, is hoe om te gaan met lifecycle informatie van een betreffende API (zie ook #622 en #468).
Dit voorstel geeft providers de mogelijkheid om toekomstige uitfasering en deprecation uit te drukken en aan te leveren aan het API register (en/of andere applicaties) die dat vervolgens weer kan tonen/notificeren aan consumers.
Gegeven:
info.version wordt volgens ADR gebruikt om huidige volledige versie van de API uit te drukken.info.version is hier niet voor bedoeld vanuit OAS, maar zo wordt hij wel gebruikt, dus dat nemen we voor lief.- Er is geen manier om gestandaardiseerd in OAS aan te geven of een API deprecated of sunset is, ook niet in OAS 3.1 (wordt wel genoemd in OAS 4.0 Moonwalk maar dit duurt nog wel even).
- Er is wél een manier om gestandaardiseerd in de response aan te geven of een API deprecated of sunset is, namelijk RFC9745
- We willen af van daadwerkelijk requests doen en zoveel mogelijk uit de OAS halen. Implementeren van RFC9745 biedt daarom op korte termijn weinig meerwaarde en kan bovendien impact hebben op huidige API's.
Voorstel:
- We nemen terminologie (
deprecated en sunset) over van RFC9745.
deprecated kan een datum in het verleden of in de toekomst zijn (hierin volgen we RFC9745)sunset kan alleen een datum in de toekomst zijn (hierin volgen we RFC9745). Na deze datum is de API ook niet meer bereikbaar dus komt er helemaal geen response meer.- We drukken deze velden uit als optionele extensies in een OAS, als onderdeel van het
info object (waar dus ook de huidige API version staat).
- Dit is geen breaking change en dus wel backwards compatible; momenteel wordt het namelijk helemaal niet uitgedrukt en het is bovendien optioneel.
Voorbeeld:
openapi: 3.0.0
info:
version: 1.2.3
x-deprecated: 2025-10-10
x-sunset: 2027-11-11
TBD: Datumnotatie
RFC9745 schrijft voor dat deprecated een UNIX timestamp is, terwijl sunset een volledige datetime is. Wat mij betreft houden wij het simpel en kiezen we voor een simpel OAS date format: YYYY-mm-dd.
Feedback gewenst aangezien men hierop zit te wachten ;-)
Discussie die al heel lang loopt terwijl de behoefte ernaar groeit, zeker als het gaat om publicatie in het API register, is hoe om te gaan met lifecycle informatie van een betreffende API (zie ook #622 en #468).
Dit voorstel geeft providers de mogelijkheid om toekomstige uitfasering en deprecation uit te drukken en aan te leveren aan het API register (en/of andere applicaties) die dat vervolgens weer kan tonen/notificeren aan consumers.
Gegeven:
info.versionwordt volgens ADR gebruikt om huidige volledige versie van de API uit te drukken.info.versionis hier niet voor bedoeld vanuit OAS, maar zo wordt hij wel gebruikt, dus dat nemen we voor lief.Voorstel:
deprecatedensunset) over van RFC9745.deprecatedkan een datum in het verleden of in de toekomst zijn (hierin volgen we RFC9745)sunsetkan alleen een datum in de toekomst zijn (hierin volgen we RFC9745). Na deze datum is de API ook niet meer bereikbaar dus komt er helemaal geen response meer.infoobject (waar dus ook de huidige API version staat).Voorbeeld:
TBD: Datumnotatie
RFC9745 schrijft voor dat
deprecatedeen UNIX timestamp is, terwijlsunseteen volledige datetime is. Wat mij betreft houden wij het simpel en kiezen we voor een simpel OASdateformat:YYYY-mm-dd.Feedback gewenst aangezien men hierop zit te wachten ;-)