Definieer nieuwe regel voor publiceren van landing page

Deze nieuwe regel zorgt ervoor dat consumers de API kunnen vinden en informatie
over de API kunnen lezen. Als deze root resource niet gedefinieerd is (en dus in
bijvoorbeeld een 404 resulteren), kunnen consumers onbewust concluderen dat de
API niet bestaat, terwijl dat wel het geval is.

Tevens lossen we hiermee de ambiguiteit met de OData specificatie op, die aangeeft
dat de service root URL in een slash moet eindigen (en dus beschikbaar moet zijn).
Voor OData APIs moet op deze root resource het OpenAPI specification document
gepubliceerd zijn.

Fixes Geonovum/KP-APIs#514
Fixes Geonovum/KP-APIs#530
Fixes Geonovum/KP-APIs#604
Fixes Geonovum/KP-APIs#624

DesignRules.md

@@ -532,6 +532,38 @@ An API is as good as the accompanying documentation. The documentation has to be
    </dl>
 </div>
 
+<div class="rule" id="/core/doc-home-page" data-type="technical">
+  <p class="rulelab">Publish root resource as landing page</p>
+  <dl>
+      <dt>Statement</dt>
+      <dd>
+         The root resource of an API (<code>/</code>) MUST result in a 200 or 30X status.
+      </dd>
+      <dt>Rationale</dt>
+      <dd>
+         <p>Consumers of an API need to know that the API exists. A landing page at the root resource (append <code>/</code> to the service root URL) MUST return a 200 or 30X status. Depending on your API, you SHOULD include one of the following options:
+         <ul>
+            <li>The root resource shows a landing page with documentation about the API</li>
+            <li>The root resource redirects to a landing page</li>
+            <li>The root resource returns data as part of your API contract</li>
+         </ul>
+         <p class="note">If this API implements the [[?OData]] specification, the landing page MUST show the OpenAPI specification document</li>
+         <div class="example">
+            <p>The root resource for an API published at <code>https://api.example.org/v1</code>:</p>
+            <pre class="nohighlight">https://api.example.org/v1/</pre>
+         </div>
+      </dd>
+      <dt>Implications</dt>
+      <dd>
+         This rule can be tested automatically and an example of the test is included in the automatic tests on <a href="https://developer.overheid.nl/">developer.overheid.nl</a>. The specific tests are published in the [[ADR-Validator]] repository.
+      </dd>
+      <dt>How to test</dt>
+      <dd>
+         The server root URL appended with a <code>/</code> MUST result in a HTTP 200 or 30X status</li>
+      </dd>
+   </dl>
+</div>
+
 ## Versioning
 
 Changes in APIs are inevitable. APIs should therefore always be versioned, facilitating the transition between changes.

js/config.js

@@ -47,4 +47,14 @@ var respecConfig = {
   specStatus: "WV",
   specType: "ST",
   pluralize: true,
+
+  localBiblio: {
+    OData: {
+      authors: ["Michael Pizzo", "Ralf Handl", "Martin Zurmuehl"],
+      date: "23 April 2020",
+      href: "https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html",
+      publisher: "OASIS Standard",
+      title: "OData Version 4.01. Part 2: URL Conventions",
+    },
+  },
 };