REST-API Design Rules 1.0, compliance, API-51

[sjaakd]

Probleem:

Wij maken REST API's tbv de Basis Registratie Ondergrond (BRO). Echter we lopen tegen een probleem in "REST-API Design Rules 1.0" aan. Zie ook: hier.

Standaard levert onze software een yaml bestand uit. Dit is conform de micro-profile specificatie.

Bechrijving:

De uitgifte wordt gecontroleerd door een Accept header mee te sturen in het verzoek. Als deze niet wordt meegestuurd dan is het standaard formaat YAML, zie hoofdstuk 5.2 in de micro-profile specificatie:

The default format of the /openapi endpoint is YAML. Vendors must also support the JSON format if the request contains an Accept header with a value of application/json, in which case the response must contain a Content-Type header with a value of application/json.

Oplossing:

Het zou mooi zijn als de "REST-API Design Rules 1.0" hierin de microprofile standaard gaat volgen. Deze wordt veelvuldig toegepast in de Java wereld. Dus: maak de Accept header sturend voor het resultaat wat wordt geretourneerd en leg geen "default" op.

[fterpstra]

@joostfarla @jasperroes Ik denk dat dit een interessant punt is om te bespreken in het kader van beheer

[joostfarla]

In design rule API-51 wordt de aanbeveling uit de OpenAPI Specification gevolgd, namelijk:

It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml.

Ten behoeve van interoperabiliteit vereisen we daarbij minimaal het JSON formaat.

De MicroProfile specificatie is een platform/framework-specifieke standaard, die een afwijkende keuze heeft gemaakt. Hoewel het conform de HTTP specificatie zuiverder zou zijn om altijd content negotiation toe te passen, zie je dat dit in de praktijk voornamelijk wordt toegepast voor dynamische operaties. Bij statische assets (zoals afbeeldingen, PDFs en tekstbestanden) wordt over het algemeen geen content negotiation toegepast.

Daar komt een aanvullende uitdaging bij, namelijk dat er voor OpenAPI documenten, maar ook voor YAML, geen officieel media type is geregistreerd bij IANA. Binnen de OpenAPI community leeft al sinds 2014 een discussie of er een dergelijke media type zou moeten komen of niet. Voor YAML worden verschillende media types, zoals application/yaml,text/yaml en application/x+yaml gebruikt. Dat zou je dan ook weer moeten standaardiseren. Plus, je zult dan hetzelfde moeten doen voor externe componenten ($ref URIs).

Concluderend lijkt het me verstandig om de bestaande design rule in stand te houden.

Om toch te kunnen voldoen aan deze design rule zou je 1 van de volgende suggesties kunnen proberen:

• Laat de Java applicatie het pad openapi.json/openapi.yaml afhandelen en intern forwarden naar de MicroProfile controller.
• Maak een export van de YAML/JSON documenten en host deze als statische files.
• Laat een reverse proxy de URL /openapi.json//openapi.yaml forwarden naar /openapi, voorzien van de juiste Accept header.

[mrtn78]

Met de toelichting van Joost is vanuit de werkgroep normatieve rules besloten dit issue te sluiten en geen aanpassing te doen in de normatieve rule API-51.