Merge pull request #144 from Logius-standaarden/develop

Publicatie van ADR 2 naar de main branche

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Kennisplatform APIs Issue base
+    url: https://github.com/Geonovum/KP-APIs/issues/
+    about: Please submit issues here.

.github/workflows/build.yml

@@ -0,0 +1,20 @@
+name: Build and Check
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+jobs:
+  build:
+    name: Build
+    uses: Logius-standaarden/Automatisering/.github/workflows/build.yml@main
+  check:
+    needs: build
+    name: Check
+    uses: Logius-standaarden/Automatisering/.github/workflows/check.yml@main    
+  publish:
+    needs: build
+    name: Publish (Logius)
+    uses: Logius-standaarden/Automatisering/.github/workflows/publish.yml@main
+    secrets: inherit

Abstract.md

@@ -0,0 +1,3 @@
+This document contains a normative standard for designing APIs in the Dutch Public Sector.  
+[The Governance of this standard](https://publicatie.centrumvoorstandaarden.nl/api/adr-beheer/) is described in a [separate repository](https://github.com/Logius-standaarden/ADR-Beheermodel) and published by Logius.  
+This document is part of the *Nederlandse API Strategie*, which consists of [three distinct documents](https://www.geonovum.nl/themas/kennisplatform-apis#APIStrategie).  

Glossary.md

@@ -0,0 +1,34 @@
+## Glossary
+
+<dl>
+  <dt>
+    <dfn>Resource</dfn>
+  </dt>
+  <dd>
+    A resource is the key abstraction of information, where every piece of information is identified by a globally unique [=URI=].
+  </dd>
+  <dt>
+    <dfn>Singular resource</dfn>
+  </dt>
+  <dd>
+    A singular resource is a resource describing a single thing (e.g. a building, person or event).
+  </dd>
+  <dt>
+    <dfn>Collection resource</dfn>
+  </dt>
+  <dd>
+    A collection resource is a resource describing multiple things (e.g. a list of buildings).
+  </dd>
+  <dt>
+    <dfn>URI</dfn>
+  </dt>
+  <dd>
+    A URI [[rfc3986]] (Uniform Resource Identifier) is a globally unique identifier for a resource.
+  </dd>
+  <dt>
+    <dfn>OGC</dfn>
+  </dt>
+  <dd>
+    The <a href="https://www.ogc.org/">Open Geospatial Consortium</a> (OGC) is a consortium of experts committed to improving access to geospatial, or location information.
+  </dd>
+</dl>

Governance/readme.md

@@ -0,0 +1,13 @@
+# Readme
+
+This folder used to hold concept information and documents related to the Governance of the API Design Rules Standard.  
+
+The governance documentation has been moved to a separate repository located at [https://github.com/Logius-standaarden/ADR-Beheermodel](https://github.com/Logius-standaarden/ADR-Beheermodel)  
+
+> The final version is published at [https://logius-standaarden.github.io/ADR-Beheermodel/](https://logius-standaarden.github.io/ADR-Beheermodel/)  
+
+
+## More information
+
+For more information about het API Standards visit [https://www.logius.nl/diensten/api-standaarden](https://www.logius.nl/diensten/api-standaarden)
+

Introduction.md

@@ -0,0 +1,40 @@
+# Introduction
+
+## Goal
+
+More and more governmental organizations offer REST APIs (henceforth abbreviated as APIs), in addition to existing interfaces like SOAP and WFS. These APIs aim to be developer-friendly and easy to implement. While this is a commendable aim, it does not shield a developer from a steep learning curve getting to know every new API, in particular when every individual API is designed using different patterns and conventions.
+
+This document aims to describe a widely applicable set of design rules for the unambiguous provisioning of REST APIs. The primary goal is to offer guidance for organizations designing new APIs, with the purpose of increasing developer experience (DX) and interoperability between APIs. Hopefully, many organizations will adopt these design rules in their corporate API strategies and provide feedback about exceptions and additions to subsequently improve these design rules.
+
+## Status
+
+This version of the design rules has been submitted to Forum Standaardisatie for inclusion on the Comply or Explain list of mandatory standards in the Dutch Public Sector. This document originates from the document [API Strategie voor de Nederlandse Overheid](https://docs.geostandaarden.nl/api/vv-hr-API-Strategie-20190715/), which was recently split into separate sub-documents.
+
+## Authors
+
+Despite the fact that two authors are mentioned in the list of authors, this document is the result of a collaborative effort by the members of the *API Design Rules Working Group*.
+
+## Reading Guide
+
+This document is part of the *Nederlandse API Strategie*.
+
+The Nederlandse API Strategie consists of [three layers of distinct documents](https://www.geonovum.nl/themas/kennisplatform-apis#APIStrategie).
+
+| Part | Description                                  | Status      | Link                                                  |
+| ---- | -------------------------------------------- | ----------- | ----------------------------------------------------- |
+| I    | General description of the API Strategy      | Informative | https://docs.geostandaarden.nl/api/API-Strategie/     |
+| IIa  | Standard for designing APIs                  | Normative   | https://publicatie.centrumvoorstandaarden.nl/api/adr/ |
+| IIb  | Extension on the Standard for designing APIs | Informative | https://docs.geostandaarden.nl/api/API-Strategie-ext/ |
+
+Before reading this document it is advised to gain knowledge of the three documents, in particular [the architecture section of part I](https://docs.geostandaarden.nl/api/API-Strategie/#architectuur).
+
+An overview of all current documents is available in this Dutch infographic:
+<figure>
+  <object data="https://geonovum.github.io/KP-APIs/media/API_infographic.svg" type="image/svg+xml" id="infographic">NL API Strategie Infographic</object>
+  <figcaption>NL API Strategie Infographic</figcaption>
+</figure>
+
+## Extensions
+<aside class="note">
+In addition to this (normative) document, separate modules are being written to provide a set of extensions. These modules are all separate documents and exists in a <a href="https://geonovum.github.io/KP-APIs/">latest editor's draft</a> (<i>Werkversie</i> in Dutch). The latest editor's draft is actively being worked on and can be found on <a href="https://github.com/Geonovum/KP-APIs">GitHub</a>. It contains the most recent changes.
+</aside>

README.md

@@ -1,15 +1,40 @@
 ## API Design Rules
 
+### NEWS!! - 6 oktober 2023 start de openbare consultatie van de API Design Rules v2 - !!NEWS
+
+- De consultatie versie 2.0.0-rc.1 is beschikbaar op: https://logius-standaarden.github.io/API-Design-Rules/
+
+### Links
+
 **API Design Rules** -- normative standard for the design of APIs for the Dutch Public Sector
 
-Bekijk hier de **laatste vastgestelde versie** van de standaard:
+Bekijk hier de **laatste vastgestelde versie** van de standaard:  
+
+- [NLGov API Design Rules v1](https://gitdocumentatie.logius.nl/publicatie/api/adr/)
+
+Bekijk hier **de laatste werkversie** van de standaard:  
+
+- https://Logius-standaarden.github.io/API-Design-Rules/
 
-https://publicatie.centrumvoorstandaarden.nl/api/adr/
+Het **Beheermodel** voor deze standaard is gepubliceerd op:  
 
-Bekijk hier **de laatste werkversie** van de standaard:
+- https://publicatie.centrumvoorstandaarden.nl/api/adr-beheer/
 
-https://Logius-standaarden.github.io/API-Design-Rules/
+### Versie 2.0.0 (juli 2023)
+
+Versie 2 van de API designrules is  gereed. Onderdeel van het besluitvormingsproces om deze versie als de nieuwe standaard vast te stellen is dat we deze versie eerst met de werkgroep API-designrules bespreken. Bij een positief advies vanuit de werkgroep kan het vaststellingsproces verder in gang gezet worden. Op 5 september is tijdens de digitale werkgroepbijeenkomst de nieuwe versie van de designrules besproken en is besloten welke wijzigingen akkoord zijn. Eventuele feedback kun je ook voor de bijeenkomst al doorgeven via een issue op [de github van het Kennisplatform.](https://github.com/Geonovum/KP-APIs/issues)
+
+Een overzicht van de nog te bespreken wijzigingen is te vinden op:
+- https://github.com/Logius-standaarden/API-Design-Rules/pulls?q=is%3Apr+is%3Aopen+label%3A%22Status%3A+In+review%22
+>Hierbij kan men indien gewenst nog direct feedback geven op de voorgestelde change.
+ 
+Een overzicht van reeds besproken wijzigingen is te vinden op:
+- https://github.com/Logius-standaarden/API-Design-Rules/pulls?q=is%3Apr+is%3Aclosed+label%3A%22Status%3A+In+review%22
+>Hier heeft de werkgroep eerder over gesproken en feedback kan als issue worden vastgelegd.
+ 
+Ook is er een concept van de releasenotes beschikbaar waarin alle wijzigingen zijn opgesomd. zie hiervoor:
+- https://github.com/Geonovum/KP-APIs/blob/master/overleggen/Werkgroep%20API%20design%20rules/Verslagen/20230905/Releasenotes_ADR2.md
 
-**Deze repository**:
+### Deze repository:  
 
 https://github.com/Logius-standaarden/API-Design-Rules/

Summary.md

@@ -0,0 +1,13 @@
+## Summary
+
+### Normative Design Rules
+
+Design rules can be technical rules, which should be tested automatically and functional rules which should be considerd when designing and building the api.
+
+#### List of functional rules
+
+<ul id="functionalList"></ul>
+
+#### List of technical rules
+
+<ul id="technicalList"></ul>