Regel voor gebruik RFC 9457

[sanderke]

De linter bevatte reeds een regel voor het verschaffen van "problem details". Hier wordt het ook als design rule toegevoegd.

fixes #188

[github-actions]

Preview link voor pull request
Diff met W3CDiff

[TimvdLippe]

API-Design-Rules/linter/spectral.yml

Line 159 in b6f040a

nlgov:use-problem-schema:

moet ook een verwijzing krijgen naar deze nieuwe regel

[TimvdLippe]

Besproken om de volgende velden als verplicht voor te stellen:

1. status
2. title
3. detail

Optioneel zijn de velden

1. type
2. instance

Er mogen geen andere velden gespecificeerd worden. De linter moet daarom geupdate worden dat het JSON object de verplichte velden bevat, en als er meer velden zijn enkel die optioneel zijn. Elk ander veld moet een error opleveren.

[TimvdLippe]

TBD vanuit #275 van @joostfarla :

• Index vs multi-valued parameters vs collection styles
• What is required / optional?
• Can request and response encodings differ? JSON input, but XML output? (hopefully not)
• Should API's evaluate the full request body, or may it stop after the first violation?

[TimvdLippe]

Met de laatste commit hebben we de linter regels. De statistieken:

Statistics for rule nlgov:use-problem-schema:

Analyzed: 160
Passing: 47
Percentage: 29%

Statistics for rule nlgov:problem-schema-members:

Analyzed: 160
Passing: 157
Percentage: 98%

Statistics for rule nlgov:problem-schema-members-bad-request:

Analyzed: 160
Passing: 66
Percentage: 41%

[TimvdLippe]

En de regel voor het vereisen van 400 bij parameters:

Statistics for rule nlgov:problem-invalid-input:

Analyzed: 160
Passing: 105
Percentage: 65%

[TimvdLippe]

Notulen:

• Voeg regel toe voor het uitvoeren van alle schema checks en alle errors in 1 keer terug geven
• Headers laten we buiten beschouwing, omdat die meestal in andere 4XX en 5XX errors resulteren
• Location maken we een String om zo te zorgen dat het zowel JSON pointer als XPath aan kan. Tevens halen we index weg voor query parameter errors, waar die informatie dan in de message moet. Daar moeten we dan een note voor toevoegen
• Apart hoofdstuk voor Content Negotiation, om zo iets te zeggen hoe application/json en application/problem+json te zetten. Dit vereist meer discussie en is een algemeen concern, dus pakken we apart op

[TimvdLippe]

De "vereis 400 voor invalid input" check heb ik nu gefixt zodat het bij GET requests enkel als er parameters zijn, en voor alle andere endpoints. Hier nog wat extra statistieken:

Alle endpoints behalve GET:

Statistics for rule nlgov:problem-invalid-input:

Analyzed: 160
Passing: 155
Percentage: 96%

Alle endpoints en GET als het parameters heeft:

Statistics for rule nlgov:problem-invalid-input:

Analyzed: 160
Passing: 104
Percentage: 65%

[TimvdLippe]

Deze wijziging is goedgekeurd bij het TO 2025-12-02 voor consultatie bij Kennisplatform API's. Dat houdt in dat we het hoofdstuk "Error handling" als geheel consulteren.

Omdat de slagingspercentages behoorlijk verschillen voor de verschillende regels, is het voorstel om MUST toe te passen voor >80% en RECOMMENDED voor alle anderen. Met uitzondering van de MIME type, waar er verwachte minieme impact is op implementaties van clients. Deze verwachting moet worden getoetst bij Kennisplatform API's.