eDelivery REST API lessons learned toepassen in API Design Rules

[edwinwisse]

In EU kader wordt een API ontwikkeld voor berichtenverkeer. Dit is een uitbreiding op de bestaande eDelivery standaard.

Zie https://ec.europa.eu/digital-building-blocks/wikis/pages/viewpage.action?pageId=388399321

[edwinwisse]

De documentatie van de eDelivery REST API pilot is hier te vinden. Het is een afgeronde pilot die onder het ISA2 programma uitgevoerd is. Dit is de opgeleverde documentatie. Op dit moment is er nog geen concreet vervolg onder het nieuwe Interoperable Europe programma.

[edwinwisse]

API beveiliging hier toegevoegd vanwege de OAuth aspecten van de pilot. API strategie en API architectuur vanwege de vraag hoe we aansluiten op internationale ontwikkelingen.

[edwinwisse]

We hebben een korte analyse gemaakt van mogelijke wijzigingen in ADR, OAuth e.d. Te vinden op eDelivery REST API, lessons to be learned

Life cycle management van de eDelivery REST API is op grote lijnen overeenkomstig ADR regels.

• Net als API rule 16 vereist het eDelivery REST API profiel het gebruik van OAS voor documentatie van API's. Er is wel een verschil in de gebruikte versie 3.1 tov 3.0
• Net als API rule 18 vereist het eDelivery REST API profiel een deprication schedule, dit is uitvoeriger beschreven par 5.3.2. In de ADR wordt dit wel benoemd maar niet gespecificeerd. We kunnen rule 18 dus hiermee verrijken.
• Net als API rule 19 vereist het eDelivery REST API profiel een transition period for new major versions, beschreven in par 5.3.1.2 ook dit onderwerp wordt in de ADR wel benoemd maar niet zo uitvoerig gespecificeerd als in het eDelivery REST API profiel. We kunnen rule 19 dus hiermee verrijken.
• Net als API rule 56 vereist het eDelivery REST API profiel SEMVER, beschreven in par 5.3.1.
• Sunsetting van operations is niet expliciet benoemd in de ADR maar wel in het eDelivery REST API profiel. dit kunnen we in de ADR dus toevoegen.
• Net als API rule 20 vereist het eDelivery REST API profiel een major version nummer in de URI

Verder is ook uitgebreider beschreven wat backwards compatibility inhoud. Kortom de life cycle beschrijving is uitgebreider dan die in de ADR en kan gebruikt worden om de ADR specifieker te maken op deze punten.

Zie 5.3 in het REST API Profile Version 1.0.

[mrtn78]

afgesproken om deze op te pakken in een nieuwe branche nadat de modulaire opbouw is doorgevoerd.

[mrtn78]

Zie ook de volgende pull requests met aanpassingen:
Logius-standaarden/API-Design-Rules#135

• Net als API rule 18 vereist het eDelivery REST API profiel een deprication schedule, dit is uitvoeriger beschreven par 5.3.2. In de ADR wordt dit wel benoemd maar niet gespecificeerd.

Rule 18 /core/deprecation-schedule is aangevuld met de inzichten vanuit eDelivery.

• Net als API rule 19 vereist het eDelivery REST API profiel een transition period for new major versions, beschreven in par 5.3.1.2 ook dit onderwerp wordt in de ADR wel benoemd maar niet zo uitvoerig gespecificeerd als in het eDelivery REST API profiel.

Rule 19 core/transition-period is aangevuld met de inzichten vanuit eDelivery.

• Net als API rule 20 vereist het eDelivery REST API profiel een major version nummer in de URI

Rule 20 /core/uri-version heeft alleen een verwijzing gekregen dat deze rule in line is met de [[eDelivery API4IPS]] specification.

• Net als API rule 56 vereist het eDelivery REST API profiel SEMVER, beschreven in par 5.3.1.

Rule 56 /core/semver heeft alleen een verwijzing gekregen dat deze rule in line is met de [[eDelivery API4IPS]] specification.

[mrtn78]

Added two additional rules regarding:

• backward compatibility
• sunsetting APIs

Zie ook de volgende pull request:
Logius-standaarden/API-Design-Rules#136