In /core/doc-openapi-contact staat dat in de OAS specificatie het contact blokje optioneel is (maar wel gewenst: SHOULD).
En als dat blokje opgenomen wordt, zowel naam, als url als e-mail gevuld moeten (MUST) worden.
De logica daarvan ontgaat me volledig. Omgekeerd zou veel logischer zijn:
- je moet (MUST) contact informatie opnemen
- het wordt aanbevolen (SHOULD) zoveel en expliciet mogelijke contact informatie op te nemen (naam, url én e-mail).
De huidige situatie is:
- als we helemaal geen contact informatie opnemen voldoen we aan de standaard
- als we alleen een url naar een contact-pagina opnemen voldoen we niet aan de standaard
In veel gevallen is het opnemen van met name het e-mailadres en naam niet optimaal. Voor verschillende doelgroepen en verschillende doelstellingen zijn verschillende communicatiemiddelen het beste.
- Bijvoorbeeld voor aansluiten is er wellicht een contactformulier op de site, of een e-mailadres om aansluitinformatie te ontvangen
- Bijvoorbeeld voor wensen is er een GitHub pagina en/of contact met een product owner
- Bijvoorbeeld voor verstoringen is er een service desk e-mailadres en/of telefoonnummer
Als je maar één e-mailadres met één naam kan en moet geven, betekent dit dat afnemers dit e-mailadres gaan gebruiken waar het niet voor bedoeld is. Dat geeft vertraging en irritaties, en dat is precies wat je niet wilt. Daarom is juist goede communicatie nodig, en dat geef je het beste op een webpagina, die naar de verschillende communicatiemiddelen kan doorverwijzen.
Ik vind daarnaast dat een OpenAPI specificatie zonder verdere verwijzing naar aanvullende informatie (contact, getting started, enz.) onwenselijk. Ook als de API specificaties alleen via een website worden aangeboden (en je dus denkt dat ze die site al kennen), kunnen mensen die specificaties op allerlei manieren krijgen. Het is immers een document dat je ook rond kan sturen.
Dus de eis SHOULD is voor een publieke API m.i. te licht en zou eigenlijk MUST moeten zijn.
Dus mijn voorstel is:
Statement
OpenAPI definition document MUST include the [info.contact](https://spec.openapis.org/oas/v3.0.1.html#contact-object) object for publicly available APIs.
The info.contact object MUST include at least one of the fields url and email.
The info.contact object MAY include the field name.
Contact information SHOULD NOT be a generic contact address for the whole organisation.
In /core/doc-openapi-contact staat dat in de OAS specificatie het contact blokje optioneel is (maar wel gewenst: SHOULD).
En als dat blokje opgenomen wordt, zowel naam, als url als e-mail gevuld moeten (MUST) worden.
De logica daarvan ontgaat me volledig. Omgekeerd zou veel logischer zijn:
De huidige situatie is:
In veel gevallen is het opnemen van met name het e-mailadres en naam niet optimaal. Voor verschillende doelgroepen en verschillende doelstellingen zijn verschillende communicatiemiddelen het beste.
Als je maar één e-mailadres met één naam kan en moet geven, betekent dit dat afnemers dit e-mailadres gaan gebruiken waar het niet voor bedoeld is. Dat geeft vertraging en irritaties, en dat is precies wat je niet wilt. Daarom is juist goede communicatie nodig, en dat geef je het beste op een webpagina, die naar de verschillende communicatiemiddelen kan doorverwijzen.
Ik vind daarnaast dat een OpenAPI specificatie zonder verdere verwijzing naar aanvullende informatie (contact, getting started, enz.) onwenselijk. Ook als de API specificaties alleen via een website worden aangeboden (en je dus denkt dat ze die site al kennen), kunnen mensen die specificaties op allerlei manieren krijgen. Het is immers een document dat je ook rond kan sturen.
Dus de eis SHOULD is voor een publieke API m.i. te licht en zou eigenlijk MUST moeten zijn.
Dus mijn voorstel is: