Onderscheid "How to test" en hoe de ADR validator iets test

[dvh]

"How to test" beschrijft testscenario's om na te gaan of een rule voldoet. Dit wil echter niet zeggen dat ze ook allemaal automatisch door (externe, in dit specifieke geval developer.overheid.nl) tools getest kunnen worden, bijvoorbeeld in de volgende scenario's:

• POST, PUT, PATCH, DELETE calls kunnen niet getest worden
• Niet alle rules van een API achter authenticatie kunnen getest worden

Voorstel is dan ook om tooling zoals de ADR validator los te trekken van de standaard. "How to test" is de verantwoordelijkheid van de API provider zelf, (handmatig of met bestaande tools zoals bijv. Postman), net als dat het in sync houden van de OAS met de daadwerkelijke API de verantwoordelijkheid is van de API provider.

De aanwezigheid van OAS is daarentegen, naast 2 van de 8 technical rules van ADR, een standaard op zichzelf. Eén van de belangrijkste argumenten om OAS te publiceren is dat de scope van een API in een machine-leesbaar formaat gepubliceerd wordt, zodat je bijvoorbeeld automatisch kunt testen of het API Design zoals gespecificeerd in OAS voldoet aan bepaalde API Design Rules. Op basis van OAS kunnen we met tools wél het hele API Design analyseren (inclusief POST, PUT, PATCH, DELETE en operaties achter authenticatie) en beoordelen.

"How the ADR Validator tests this" zou een extra kopje kunnen zijn, maar zou ook in zijn geheel beschreven kunnen worden als onderdeel van de validator in plaats van de standaard. Ik pleit zelf voor het laatste.