From 3483e015ddb3cf7734e3351aa49723140508998c Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Wed, 22 Jan 2025 16:09:09 +0100 Subject: [PATCH 1/3] Voeg contact informatie toe aan OpenAPI document Hiermee wordt het voor publiek beschikbare APIs makkelijker om contact op te zoeken met de owners als er vragen of problemen zijn met deze API. Voor interne APIs waar er al een communicatie kanaal bestaat (bijvoorbeeld voor een API die binnen eenzelfde organisatie door 1 team wordt gebouwd) is deze requirement niet nodig. --- DesignRules.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/DesignRules.md b/DesignRules.md index 56f37c8..319c899 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -434,6 +434,27 @@ An API is as good as the accompanying documentation. The documentation has to be +
+

Document contact information for publicly available APIs

+
+
Statement
+
+ OpenAPI definition document SHOULD include the info.contact object for publicly available APIs. +
+
Rationale
+
+ The OpenAPI Specification (OAS) [[OPENAPIS]] can include contact information to make clear how to reach out to API owners in case of issues or questions. This is relevant for publicly available APIs (such as OData) where no pre-existing communication channel exists between provider and consumer of the API. For internal APIs (where communication channels such as chat or issue trackers can suffice), the info.contact MAY be provided. +
+
Implications
+
+ This rule can be tested automatically and an example of the test is included in the automatic tests on developer.overheid.nl. The specific tests are published in the [[ADR-Validator]] repository. +
+
How to test
+
+
+
+
+

Publish documentation in Dutch unless there is existing documentation in English

From 5b1f571aa9aeeccb1751670111a659a286bdc4cb Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Thu, 23 Jan 2025 11:16:12 +0100 Subject: [PATCH 2/3] Specificeer dat generieke contact informatie niet de bedoeling is --- DesignRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DesignRules.md b/DesignRules.md index 319c899..a602807 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -439,7 +439,7 @@ An API is as good as the accompanying documentation. The documentation has to be
Statement
- OpenAPI definition document SHOULD include the info.contact object for publicly available APIs. + OpenAPI definition document SHOULD include the info.contact object for publicly available APIs. Contact information SHOULD NOT be a generic contact address for the whole organisation.
Rationale
From ce702db415d26131416094766c81d77f90b0d708 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Wed, 5 Feb 2025 13:40:19 +0100 Subject: [PATCH 3/3] Voeg voorbeeld toe voor contact informatie Naar aanleiding van een suggestie in het TO om ook expliciet een voorbeeld toe te voegen waarbij de issue tracker prominent naar voren komt. --- DesignRules.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/DesignRules.md b/DesignRules.md index a602807..ff95bae 100644 --- a/DesignRules.md +++ b/DesignRules.md @@ -443,7 +443,15 @@ An API is as good as the accompanying documentation. The documentation has to be
Rationale
- The OpenAPI Specification (OAS) [[OPENAPIS]] can include contact information to make clear how to reach out to API owners in case of issues or questions. This is relevant for publicly available APIs (such as OData) where no pre-existing communication channel exists between provider and consumer of the API. For internal APIs (where communication channels such as chat or issue trackers can suffice), the info.contact MAY be provided. + The OpenAPI Specification (OAS) [[OPENAPIS]] can include contact information to make clear how to reach out to API owners in case of issues or questions. This is relevant for publicly available APIs (such as OData) where no pre-existing communication channel exists between provider and consumer of the API. For internal APIs (where communication channels such as chat or issue trackers are likely already known), the info.contact MAY be provided. +
+

Relevant contact information can include an email address and issue tracker.

+ 
{
+  "name": "Gebouwen API beheerder",
+  "url": "https://www.github.com/ministerie/gebouwen/issues",
+  "email": "teamgebouwen@ministerie.nl"
+}
+
Implications