search

Geonovum / KP-APIs

25 stars 40 forks source link

Standaardiseren API Lifecycle Management #622

Open dvh opened 3 months ago

dvh commented 3 months ago

Het enige dat de NL API Strategie nu zegt over de lifecycle van een API is hoe om te gaan met versioning. Echter, hoe om te gaan met (aangekondigde) deprecations en retirements van APIs tijdens de end-of-life phase van een API, wordt niet belicht. Bij DSO wordt gebruik (misbruik) gemaakt van de Warning reponse header (zie ook issue #177), maar zij zijn op zoek naar een alternatief vanwege hun migratie naar de NL API Strategie.

Voor het gebruik van response headers verwijs ik graag naar een best practice die hier specifiek voor bedoeld is, namelijk de Deprecation en Sunset headers zoals beschreven in https://blog.axway.com/learning-center/apis/api-management/api-lifecycle-management-deprecation-and-sunsetting en issue #225.

Los van deze headers is er ook nog de mogelijkheid om de huidige phase van een API met een OAS extensie aan te geven. Onze Italiaanse collega's gebruiken bijvoorbeeld x-status in het info object om aan te geven in welke fase de API zich bevindt: active, deprecated, sunset or retired.

Voor (potentiele) API consumers is het van belang om dit ergens terug te kunnen vinden. Vanuit developer.overheid.nl (DON) zouden wij deze informatie bijvoorbeeld kunnen gebruiken om het register up to date te houden. Het is dan m.i. ook niet de bedoeling dat er APIs verwijderd worden uit het register als deze uitgefaseerd zijn.

Praktijkvoorbeeld: een bepaalde API werkte opeens niet meer. Wat bleek, de hele organisatie was opgeheven. Consumers gebruiken DON om meer info over deze API te vinden, maar volgens DON was deze online. Alternatief was om hem te verwijderen, maar dan had de consumer hem überhaupt niet kunnen vinden. Ander alternatief was om zelf een status "inactief" te verzinnen, maar deze statussen beleg ik dan liever bij het kennisplatform.

Ik stel voor dat we een topic in de API Strategie opnemen over de technische en niet-technische best practices omtrent API lifecycle management, en hieruit de uitfasering van APIs specifiek. Indien gewaardeerd schrijf ik zelf een eerste voorstel ;-)

mrtn78 commented 2 months ago

@dvh vandaag in het formele Technisch Overleg van de API Design Rules besloten om voor de volgende versie 2.1 ook dit onderwerp te adresseren. Hiervoor is eerder een analyse gedaan van de best practices die ook in de eDelivery API zijn opgenomen. Zie ook issue https://github.com/Geonovum/KP-APIs/issues/468

indien gewaardeerd kunnen we dit ook samen oppakken ;-)

dvh commented 1 month ago

Ik ben er in ieder geval wel geïnteresseerd in, dus als ik een keer ergens kan en mag aansluiten dan graag. Met developer.overheid.nl kunnen we dan wellicht alvast voorsorteren op de uitkomst. Overigens loopt deze discussie ook nog in Italië en bij OpenAPI zelf, dus lijkt me goed om daar ook naar te kijken indien dat nog niet het geval is ;-)