Contact informatie opnemen in OAS/ADR

[dvh]

Op developer.overheid.nl staan een hoop API's die geen of onrelevante contact informatie hebben. Als API consumer wil ik wél weten hoe ik de partij waarvan ik afhankelijk ben geworden (door de API te implementeren) kan benaderen. OAS heeft hier het info.contact object voor, zie ook: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#contact-object.

Het lijkt mij goed om hier iets over af te spreken in de API Design Rules of anders op een andere manier af te dwingen dat:

a) er contactgegevens van de API provider zijn en
b) deze contactgegevens relevant zijn, dus niet alle API's van Kadaster verwijzen naar [email protected] die vervolgens waarschijnlijk geen idee hebben welke afdeling over welke API gaat.

We zouden bijvoorbeeld kunnen verplichten dat info.contact gevuld is in OAS, dit kunnen we dan ook automatisch valideren. Of deze gegevens relevant zijn wordt uiteraard weer een ander verhaal.

[tomootes]

Toevallig kaartte ik dit zojuist aan bij @dvh. Ben het er dus mee eens