Design rules die waren goedgekeurd opgenomen

Design rules/Diversen.md

@@ -0,0 +1,190 @@
+---
+layout: page-with-side-nav
+title: API Kennisbank
+---
+
+## 4. Diversen
+
+### DR4.1 Identificatie van een resource zit altijd op het hoogste niveau van de resource
+
+De identificatie van een resource zit  altijd op het hoogste niveau van de resource. Als de identificatie als parameter wordt gebruikt is dat in de vorm en inhoud zoals de identificatie is opgenomen in de resource.
+
+Datum opname : 29-04-2021
+Datum wijziging : 29-04-2021
+
+### DR4.2 Neem voor properties geen waarden op met een speciale betekenis
+
+We nemen geen waarden op met een speciale betekenis die afwijkt van de normale betekenis van het gegeven.
+
+bijvoorbeeld datum "0000-00-00" om aan te geven dat een datum onbekend is
+bijvoorbeeld landcode "0000" om aan te geven dat het land onbekend is
+
+Ratio: Als er informatie beschikbaar is moet die als zondanig onderkend en gemodelleerd worden.
+
+Datum opname : 29-04-2021
+Datum wijziging : 29-04-2021
+
+### DR4.3 De description van een property moet semantisch overeenkomen met de betekenis van het gegeven in een gegevenswoordenboek (infromatiemodel)
+
+We nemen bij een property een description op die semantisch overeenkomt met de beschrijving in het gegevenswoordenboek. Deze kan ingekort, vereenvoudigd, of uitgebreid zijn, maar mag de betekenis van het gegeven niet laten afwijken van de betekenis van het corresponderende gegeven in het gegevenswoordenboek.
+
+De description kan worden weggelaten wanneer evident is dat de gebruikers van de API uit de propertynaam weten wat bedoeld wordt (bijvoorbeeld huisnummer).
+
+_**Ratio:**_ Om de description leesbaar te houden voor developers kan ervoor gekozen worden deze in te korten of
+binnen de context te vereenvoudigen.
+
+Datum opname : 29-04-2021
+Datum wijziging : 29-04-2021
+
+## DR4.4 Als meerdere componenten dezelfde properties bevatten (generalisatie) gebruik dan de 'allOf' om deze samenhang vorm te geven.
+
+Wanneer er meerdere componenten zijn met meerdere dezelfde properties, moet er hergebruik worden gemaakt via een 'allOf' constructie. Dit sluit aan op object oriëntatie in de verschillende programmeeromgevingen.
+
+Bijvoorbeeld een woonadres en een postadres zijn identiek, behalve dat postadres ook een postbusnummer kent. Dan is postadres een extensie op woonadres.
+Bijvoorbeeld een natuurlijk persoon en een niet-natuurlijk persoon hebben beide een naam en een adres, maar beide hebben ook eigen gegevens (natuurlijk persoon heeft geboortedatum, niet-natuurlijk persoon heeft eigenaar), dan zijn beide een extensie op een bovenliggende component "Persoon".
+Bijvoorbeeld bij een zakelijkGerechtigde worden alleen minimale identificerende gegevens van een persoon opgenomen (alleen naam en identificatie), maar bij de persoon (resource) worden meer eigenschappen van de persoon opgenomen (zoals adres). Dan gebruikt zakelijkGerechtigde het component "persoonBeperkt" en is de uitgebreide persoon een extensie hierop.
+
+Voorbeeld:
+
+```
+     Adres:
+      type: "object"
+      properties:
+        straat:
+          type: "string"
+          example: "Nassaulaan"
+        huisnummer:
+          type: "integer"
+          example: 12
+        postcode:
+          type: "string"
+          example: "2514JS"
+        woonplaats:
+          type: "string"
+          example: "Den Haag"
+
+      PostAdres:
+       allOf:
+         - $ref: "#/components/schemas/Adres"
+         - properties:
+             postbusnummer:
+               type: "integer"
+               example: 300
+```
+
+## DR4.5 Plaats bij het gebruik van 'allOf' het hergebruikte component als eerste.
+
+Bij het gebruik van 'allOf' staat de component die hergebruikt wordt altijd eerst, en staan de toegevoegde properties als tweede.
+
+Voorbeeld van het correct gebruik van 'allOf':
+
+```NaamPersoon:
+       allOf:
+         - $ref: "#/components/schemas/Naam"
+         - description: "Gegevens over de naam van de persoon"
+           properties:
+             aanhef:
+               type: "string"  
+```
+
+Voorbeeld van _**foutief**_ gebruik van 'allOf':
+```
+ 	NaamPersoon:
+ 	      allOf:
+ 	        - description: "Gegevens over de naam van de persoon"
+ 	          properties:
+ 	            aanhef:
+ 	              type: "string"
+ 	        - $ref: "#/components/schemas/Naam"
+```
+
+_**Ratio:**_ Afwijken van deze regel leidt tot problemen bij het genereren van code uit de API specificaties.
+
+Datum opname : 29-04-2021
+Datum wijziging : 29-04-2021
+
+## DR4.6 Bij het gebruik van 'allOf' is er slechts 1 component waarnaar gerefereerd wordt
+
+Bij gebruik van allOf is er altijd exact één component waarnaar gerefereerd wordt en één gedefinieerd object met ten minste één property.
+
+Voorbeeld van het foutief gebruik van allOf:
+
+```
+     NaamPersoon:
+       allOf:
+         - $ref: "#/components/schemas/Naam"
+         - $ref: "#/components/schemas/Aanschrijfwijze"
+         - description: "Gegevens over de naam van de persoon"
+           properties:
+             aanhef:
+               type: "string"
+```
+
+Er wordt hier uit twee componenten overgeërfd wat niet correct is.
+
+Voorbeeld van het foutief gebruik van allOf:
+```
+     NaamPersoon:
+       allOf:
+         - $ref: "#/components/schemas/Naam"
+         - description: "Gegevens over de naam van de persoon"
+```
+
+NaamPersoon heeft geen eigen properties wat niet correct is.
+
+Voorbeeld van correct gebruik van allOf:
+
+```
+     Naam:
+      type: "object"
+      properties:
+        geslachtsnaam:
+          type: "string"
+          description: |
+                        De achternaam van een persoon.
+          example: "Vries"
+        voorletters:
+          type: "string"
+          description: |
+                        De voorletters van de persoon, afgeleid van de voornamen.
+          example: "P.J."
+
+      NaamPersoon:
+       allOf:
+         - $ref: "#/components/schemas/Naam"
+         - description: "Gegevens over de naam van de persoon"
+           properties:
+             aanhef:
+               type: "string"
+             aanschrijfwijze:
+               type: "string"
+```
+
+_**Ratio:**_
+
+Afwijken van deze regel leidt tot problemen bij het genereren van code uit de API-specificaties.
+
+Datum opname: 15-04-2021
+Datum wijziging: 15-04-2021
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Wanneer er meerdere componenten zijn met meerdere dezelfde properties, moet er hergebruik worden gemaakt via een 'allOf' constructie. Dit sluit aan op object oriëntatie in de verschillende programmeeromgevingen.
+
+Bijvoorbeeld een woonadres en een postadres zijn identiek, behalve dat postadres ook een postbusnummer kent. Dan is postadres een extensie op woonadres.
+Bijvoorbeeld een natuurlijk persoon en een niet-natuurlijk persoon hebben beide een naam en een adres, maar beide hebben ook eigen gegevens (natuurlijk persoon heeft geboortedatum, niet-natuurlijk persoon heeft eigenaar), dan zijn beide een extensie op een bovenliggende component "Persoon".
+Bijvoorbeeld bij een zakelijkGerechtigde worden alleen minimale identificerende gegevens van een persoon opgenomen (alleen naam en identificatie), maar bij de persoon (resource) worden meer eigenschappen van de persoon opgenomen (zoals adres). Dan gebruikt zakelijkGerechtigde het component "persoonBeperkt" en is de uitgebreide persoon een extensie hierop.

Design rules/Naamgeving.md

@@ -66,3 +66,9 @@ _**Ratio:**_ Het is niet eenduidig of een einddatum een "tot"-datum is of een "t
 
 Datum opname : 29-04-2021
 Datum wijziging : 29-04-2021
+
+## DR1.7 Wanneer pas je enkelvoud of meervoud toe in propery-namen
+
+Als het een propertynaam is die verwijst naar eenb gerelateerde resource dan wanneer wordt de resourcenaam enkelvoud als de gerelateerde resource één keer kan voorkomen. Wanneer de gerelateerde resource meerdere keren kan voorkomen, wordt de resourcenaam in meervoud gebruikt.
+
+Als properties of gegevensgroepen meermaals kunnen voorkomen (arrays) wordt meervoud toegepast. Anders wordt enkelvoud toegepast. 

Design rules/Waarden.md

@@ -0,0 +1,142 @@
+---
+layout: page-with-side-nav
+title: API Kennisbank
+---
+
+
+# 2. Waarden, enumeraties en dynamische lijsten
+
+### DR2.1 Voor het uitdrukken van tijdsduur gebruiken we de ISO-8601 standaard
+Een toelichting is [hier](https://nl.wikipedia.org/wiki/ISO_8601) te vinden.
+
+_**Ratio:**_
+
+Dit is een veelgebruikte internationale standaard.
+
+Datum opname : 17-02-2021
+Datum wijziging : 29-04-2022 (Toelichting van ISO-8601 standaard toegevoegd)
+
+### DR2.2 Gebruik een boolean voor Ja/Nee of waar/onwaar
+
+Eigenschappen die functioneel alleen de waarde Ja/aan/waar of Nee/uit/onwaar kunnen hebben, worden gedefinieerd als boolean. We gebruiken dus geen enumeratie zoals [J,N] voor dit soort situaties.
+
+_**Ratio:**_ Een boolean is technisch eenduidiger en beter verwerkbaar voor developers.
+
+Datum opname : 29-04-2021
+Datum wijziging : 29-04-2021
+
+### DR2.3 Dynamische domeinwaarden worden in de query-parameters met de code opgenomen
+
+Voor een query-parameter waarin een entry uit een waardelijst of een landelijke tabel als selectie-criterium wordt gebruikt wordt de code van de entry gebruikt.
+
+_**Ratio:**_ De omschrijving is human readable tekst. Daar kunnen verschillen in staan, bijvoorbeeld hoofd- of kleine letters. Voor een computer een verschil, voor een mens niet. Daarnaast levert het gebruik van codes ook kortere URL's op.
+
+Datum opname : 29-04-2021
+Datum wijziging : 29-04-2021
+
+### DR2.4 Enumeratie-waarden zijn in snake_case
+
+Voor de waarden van enumeraties wordt snake_case toegepast. Deze bevatten dus alleen kleine letters, cijfers en underscores. Geen spaties, geen speciale tekens en geen hoofdletters.
+
+_**Ratio:**_ In sommige development-omgevingen leveren hoofdletters, spaties of speciale tekens in enumeratie-waarden een probleem op met code-genereren.
+
+Datum opname : 17-02-2021
+Datum wijziging : 17-02-2021
+
+### DR2.5 Schema componentnamen voor domeinwaarden en enumeraties krijgen een vaste extensie
+
+Schema componenten voor dynamische domeinwaarden (referentielijsten zoals "Tabel 32 Nationaliteitentabel") en enumeraties krijgen respectievelijk extensie "Tabel" en "Enum" zonder de toevoeging van underscores.
+
+_**Ratio:**_ Vaak heeft de property dezelfde naam als de enumeratie die aangemaakt wordt. Onderscheid is dan prettig en soms zelfs nodig i.r.t. codegenratie. Hetzelfde argument geldt voor referentielijsten.
+
+Datum opname : 29-04-2021
+Datum wijziging : 29-04-2021
+
+## DR2.6 Beperk de lengte van enumeratiewaarden
+
+De lengte van enumeratiewaarden wordt beperkt. Bijvoorbeeld "Opstalhouder Nutsvoorzieningen op gedeelte van perceel" krijgt als waarde "nutsvoorzieningen_gedeelte". Het is aan de API-designer en de betreffende community om de toe te passen waarden te bepalen. Gebruik alleen enumeraties als de waarde kort, zelfbeschrijvend en stabiel is.
+
+Als er behoefte is aan lange enumeratiewaarde is een referentielijst mogelijk een beter alternatief. Ook als de waarden van de betreffende lijst mutabel is is een referentielijst een betere keuze.
+
+Mocht het toch van belang zijn de lange omschrijving te delen met de comsumer-developer, dan kan deze lange omschrijving opgenomen worden in de description van de enumeratie. Indien gewenst zou deze lange omschrijving dan additioneel aangeboden kunnen worden als property.
+
+'''
+taal:
+  type: string
+  description: |-
+    De taal afkorting volgens ISO 639-2:
+    * dut - Dutch
+    * eng - English
+  enum:
+  - dut
+  - eng
+taalWeergave:
+  type: string
+  description: De volledige naam van de taal
+'''
+
+_**Ratio:**_
+Vanuit developer-perspectief zijn lange enumeratiewaarde onprettig om mee te werken. Ook het tonen van enumeratiewaarden in de User Interface wordt complex als de enumartiewaarden te onnodig lang zijn.
+
+Datum opname : 29-04-2022
+Datum wijziging : 29-04-2022
+
+## DR2.7 Gebruik betekenisvolle enumeratiewaarden
+
+Gebruik enumeratiewaarden die betekenisvol en begrijpelijk zijn. Dus niet M en V, maar man en vrouw. Hierbij moet een afweging gemaakt worden met het toepassen van Design Rule DR2.6
+
+_**Ratio:**_
+Een developer moet bij het coderen begrijpen wat de code betekent, om fouten in de implementatie te voorkomen.
+
+## DR2.8 Overweeg een enumeratiewaarde weer te geven als string in een bevraging-API
+
+Het toepassen van een enumratie brengt het risico van tight coupling en breaking changes met zich mee.
+
+Indien een attribuut in het informatiemodel voorkomt als enumeratie, maar de corresponderende property komt alleen voor in de response op een bevraging om aan gebruikers te worden getoond dan is het niet nodig het ook in de API specificaties als een enumeratie te definiëren.
+
+Wanneer de enumeratiewaarde gebruikt wordt in code (algoritmes), definieer dan betekenisvolle maar bondige enumeratiewaarden.
+
+_**Ratio:**_
+
+Het opnemen van een enumeratie in de API-definitie betekent dat voor het kunnen tonen van een nieuwe of gewijzigde waarde in de enumeratie een nieuwe versie van de API moet worden uitgebracht. Voor bevraging-API's is dat een ongewenste vorm van tight coupling.
+
+Als het gegeven echter wordt gebruikt in code (algoritme) dan is het van belang dat er niet afgeweken kan worden van de bekende waarden en is een definitie als enumeratie op zijn plaats.
+
+## DR2.9 Neem een indicator op om de betekenis "magic strings" expliciet te maken.
+
+Wanneer het gevuld zijn van een datum functionele betekenis heeft, ook wanneer deze volledig onbekend is, wordt een indicator opgenomen om dit aan te geven. Als bv een datum veld de waarde "00000000" bevat en dat betekenis heeft wordt niet deze ongeldige waarde opgenomen in een date-veld, maar wordt een indicator toegevoegd.
+
+Indien in het onderstaande voorbeeld er helemaal niets bekend is van de overlijdensdatum, maar er is wel bekend dat de persoon overleden is, dan kan dat nergens uit worden afgeleid. Uit de reponse kan je niet opmaken of de overlijdensdatum leeg is omdat iemand  niet is overleden of omdat de overlijdensdatum niet bekend is.
+
+```
+    Persoon:
+      type: object
+      description: "Natuurlijkpersoon of NietNatuurlijkPersoon"
+      properties:
+        identificatie:
+          type: string
+        datumOverleden:  
+          $ref: "#/components/schemas/TypePersoonEnum"type: string
+        voorletters:
+          type: string
+```
+
+Door voor een dergelijke situatie een boolean op te nemen waar de betreffende informatie wordt gerepresenteerd wordt duidelijk wat de situatie is zonder dat er invalide waardes hoeven te worden opgenomen in de datum-velden.
+
+```
+    Persoon:
+      type: object
+      description: "Natuurlijkpersoon of NietNatuurlijkPersoon"
+      properties:
+        identificatie:
+          type: string
+        datumOverleden:  
+          $ref: "#/components/schemas/TypePersoonEnum"type: string
+        indicatieOverleden:
+          type: boolean
+        voorletters:
+          type: string
+```
+
+_**Ratio:**_
+Bijvoorbeeld of een persoon overleden is kan niet worden afgeleid uit het bestaan van een overlijdensdatum wanneer die datum onbekend is. Daarvoor kan een boolean "indicatieOverleden" worden gedefinieerd.