Patch how to test

[mrtn78]

Als voorbereiding op de behandeling van de standaard door het Forum Standaardisatie en de doorontwikkeling van developer.overheid zijn de deeplinks naar de testcode verwijdert en zijn de tests algemener beschreven. Dit geeft developer.overheid meer vrijheid om verschillende manieren van testen op te zetten en uit te werken.

Conform de geest van de design rules zijn de tests meer gericht op het testen van het design aan de hand van de Open API Specification, dan aan het testen van de server configuratie waarop de API draait. ook het onderscheid tussen het design en de implementatie is niet aan ons om te testen. vandaar de focus op het design en de OAS.

Deze wijzigingen zijn ingegeven door de issues van @dvh zoals gebundeld in https://github.com/Geonovum/KP-APIs/milestone/4

De wijzigingen betreffen GEEN inhoudelijke wijzigingen van de standaard, het is slechts een aanpassing in verwijzingen naar externe bronnen en informatieve manieren om de regels van de standaard te kunnen testen.

[dvh]

Voor de besluitvorming wel goed om ook te vermelden dat dit niet enkel voor developer.overheid.nl is gedaan:

• "How to test" zou moeten beschrijven hoe je kunt testen of iets aan een regel voldoet. Dit staat los van de manier waarop je dit doet; dit kan handmatig, via eigen tools, onafhankelijke validators, etc. Omdat deze allemaal niet in beheer zijn van de organisatie die de standaard zelf beheert is een harde verwijzing in de standaard een slecht idee.
• Omdat "OpenAPI Specification" op zichzelf een verplichte standaard is, is het logisch dat bij het valideren van API Design Rules uitgegaan mag worden van de aanwezigheid van een OpenAPI Specification. Sterker nog, één van de argumenten om een OpenAPI Specification verplicht te stellen was júist dat je op een machine leesbaar formaat de scope en het gedrag van de API uitdrukt, voor bijvoorbeeld linters of validators.
• Een aantal testcases klopten sowieso niet, of schoten het doel van de regel zelf voorbij waardoor het onnodig complex was voor zowel de validerende partij als de API provider.

[TheBonheurs]

Buiten de opmerkingen van Joost en Dimitri heb ik verder geen op of aanmerkingen en kan deze gemerged worden.

[mrtn78]

• "How to test" zou moeten beschrijven hoe je kunt testen of iets aan een regel voldoet. Dit staat los van de manier waarop je dit doet; dit kan handmatig, via eigen tools, onafhankelijke validators, etc. Omdat deze allemaal niet in beheer zijn van de organisatie die de standaard zelf beheert is een harde verwijzing in de standaard een slecht idee.

Ik heb de tekst in de implication aangepast zodatduidelijk is dat het gaat om "an example of the test is included in the automatic tests..."