geonovum/kp-apis

Readme KP-APIs

Meer informatie over het Kennisplatform APIs is te vinden op de website van Geonovum. Hier vind je ook de mogelijkheid je aan te melden voor de werkgroepen, het slack kanaal en de nieuwsbrief.

De API strategie bestaat uit een een inleidend document, verschillende normatieve documenten (NL GOV standaarden) en meerdere modulen die voor verschillende functionele of technische situaties kunnen worden ingezet. Een actueel overzicht van alle documenten is weergegeven in de onderstaande infographic:

De verschillende onderdelen van de NL API Strategie bevat de volgende documenten:

Onderdeel	Documentnaam & Verwijzing naar de laatst gepubliceerde versie	Status	Versie
Algemeen	Inleiding NL API Strategie	Vastgesteld (door Kennisplatform)	21-12-2023
Algemeen	Architectuur NL API Strategie	Vastgesteld (door Kennisplatform)	21-12-2023
Algemeen	Gebruikerswensen NL API Strategie	Vastgesteld (door Kennisplatform)	21-12-2023
Normatieve standaard	API Design Rules (ADR)	Verplicht (pas toe leg uit)	09-07-2020 v1.0.0
Normatieve standaard	Open API Specification (OAS)	Verplicht (pas toe leg uit)	25-05-2018 v3.0.0
Normatieve standaard	NL GOV OAuth profiel	Verplicht (pas toe leg uit)	09-07-2020 v1.0.0
Normatieve standaard	NL GOV OpenID Connect profile	Verplicht (pas toe leg uit)	18-09-2023 v1.0.1
Normatieve standaard	Digikoppeling REST API koppelvlak specificatie	Verplicht (pas toe leg uit)	14-11-2022 v1.1.1
Normatieve module	API Geospatial Design Rules module	Vastgesteld (door Kennisplatform) (door PGDI)	23-05-2023 07-03-2024
Normatieve module	API Transport Security module	Vastgesteld (door Kennisplatform) (door PGDI)	23-05-2023 07-03-2024
Aanvullende module	API Access control module	Stabiel (Werkgroep Kennisplatform)	11-07-2023
Aanvullende module	API Naming conventions module	Stabiel (Werkgroep Kennisplatform)	12-07-2023
Aanvullende module	API Hypermedia module	Stabiel (Werkgroep Kennisplatform)	12-07-2023

Folders

De hoofdstructuur van de repository is aangepast !!!

Overzicht van de folders in de repository en het doel van de folder:

Nr	Folder	Doel
1	archief	Parkeren en bewaren alle oude files en media die niet meer actief wordt gebruikt.
2	media	Bron voor alle style sheets en media bestanden die in de tekst worden gebruikt. Zowel de bewerkbare bronbestanden als de gerenderde .svg, .png, .jpg bestanden worden in deze folder opgeslagen.
3	overleggen	Hoofdmap voor alle werkmappen van de overleggen van de stuurgroep en werkgroepen.
3.1	/Stuurgroep	Alle bestanden, verslagen en overige stukken van de stuurgroep.
3.2	/Werkgroep API architectuur	Alle bestanden, verslagen en overige stukken van deze werkgroep.
3.3	/Werkgroep API beveiliging	Alle bestanden, verslagen en overige stukken van deze werkgroep.
3.4	/Werkgroep API design rules	Alle bestanden, verslagen en overige stukken van deze werkgroep.
3.5	/Werkgroep API design visie	Alle bestanden, verslagen en overige stukken van deze werkgroep.
3.6	/Werkgroep API strategie en beleid	Alle bestanden, verslagen en overige stukken van deze werkgroep.
4	API-strategie-algemeen	Hoofdmap van de Algemene documenten van de API Strategie.
4.1	/Inleiding	Map voor het eerste inhoudelijke en inleidende document (wat iedereen moet lezen voor een algemeen beeld van de NL API Strategie.)
4.2	/Architectuur	Map voor het architectuur document van de NL API Strategie. Dit document is een verdieping van de inleiding. [ARC]
4.3	/Gebruikerswensen	Map voor het document over gebruikerswensen en het bieden van een uitstekende developer experience. [DEX]
5	API-strategie-modules	Hoofdmap voor alle modulen
5.1	/_extensies-legacy	Map voor de verzameling van oude extenties. Deze map wordt verwijdert wanneer alle extenties zijn verwerkt tot modulen.
5.2	/_template	Map voor de template die gebruikt kan worden voor nieuwe modulen
5.3	/access-control	Map voor de module access control [ACC]
5.4	/geospatial	Map voor de module geospatial [GEO]
5.5	/transport-security	Map voor de module transport security [TRS]
6	API-strategie-governance	Hoofdmap voor alle governance documenten en bestanden van het Kennisplatform APIs en de NL-API-Strategie

kp-apis's Issues

4.3.1: geen toestand & cookies of sessies

Een REST API mag geen toestand (state) bijhouden. Dit betekent dat authenticatie en autorisatie van een verzoek niet mag afhangen van cookies of sessies. In plaats daarvan wordt elk verzoek voorzien van een token.

Een session-token (in een cookie) en een API-token in een (custom) HTTP header verschillen conceptueel van elkaar door het transportprotocol. Beide transportprotocollen hebben voor en nadelen:

HTTP-only cookies kunnen niet door JavaScript gelezen worden en zijn dus minder vatbaar voor XSS. Cookies worden automatisch verstuurd, dus dat maakt ze kwetsbaar voor CSRF. Hier heeft een (custom) HTTP header value geen last van.

Ik zou het beter vinden als het transport (cookies) hier niet in een negatieve manier genoemd wordt en het onderscheid tussen transport en algoritme (signed token vs. server state) duidelijker wordt gemaakt.

Hoe omgaan met automatisch laden (embedden) van een relatieklasse

Bijvoorbeeld een persoon heeft een relatie huwelijk/geregistreerd partnerschap (in het bericht opgenomen in _links.partnerschappen en _embedded.partnerschappen). Deze nested resource bevat eigenschappen van de relatie, zoals soortVerbintenis en datumHuwelijkssluiting_aangaanGeregistreerdPartnerschap, en daarnaast de relatie naar de betreffende partner.

In veel gevallen is er behoefte aan om bij de bevraging van de persoon direct gegevens (bijvoorbeeld naam) van de partner te krijgen.
Waar we normaal gesproken maar één niveau diep zouden willen embedded (alleen de relatie), willen we in dit geval twee niveaus diep kunnen embedden.

Hoe werkt de expand parameter in dat geval?
Als ik vraag ?expand=partnerschappen, krijg ik dan altijd de gerelateerde partnergegevens ook mee in het antwoord? Of krijg ik dan alleen attributen van de partnerschappen en moet ik ook vragen om de partnergegevens?
Bijvoorbeeld wanneer ik alleen de naam van de partner wil hebben hoe doe ik dat?expand=partnerschappen._embedded.partners.naam

6.1.25 Api's controleren dat de Content-Type header is ingesteld

nogal typisch geformuleerd. Ik lees het als een eis aan requesters dat Content-Type header moet zijn ingesteld in de request. En aan providers om op Content-Type te controleren. Waarom is de regel niet gewoon: het gebruik van de Content-Type header is verplicht? Dat schept verplichtingen voor alle partijen.

Proposal: API-46 Herformuleren

API-46: Paginering wordt gerealiseerd op basis van JSON+HAL

Alleen verplicht als het media type "application/hal+json" is. De HAL-standaard is niet specifiek geschikt voor paginering maar wordt vooral gebruikt voor het faciliteren van eager loading. Als je HAL alleen voor paginering gebruikt sleept deze standaard te veel ballast mee. Bovendien is HAL een dode standaard die nauwelijks ondersteund wordt in de reguliere programmeeromgevingen van Python, C#, Java, etc.

API-43 Waar relevant wordt caching toegepast

Het gebruik van het begrip ‘relevant’ is vaag. De titel kan scherper, bijvoorbeeld door aan te geven hoe caching toegepast moet worden. Vermeld voorbeelden wanneer caching gebruikt kan worden (en dus wanneer het ‘relevant’ is). Dat helpt bij keuze bij configuratie bij dynamische en intensief geraadpleegde resources.

Voorstel voor verbetering
Voor Caching moet gebruik gemaakt worden van ETag en Last-Modified

Voorbeeld JSON envelope API-28

In hst 4.6.3 staat geen goed voorbeeld van een JSON envelope ?

TMLO: Integriteit uitwisselen over APIs

In de context van de ZDS 2.0 services was ik bezig met TMLO-integriteit informatie toe te voegen aan de API, en ik liep tegen een hoop praktische problemen aan (vooral op het gebied van machine-naar-machine communicatie). Ik denk dat het handig is om hier overeen te komen hoe dit er zou moeten uitzien op landelijk niveau, wat we vervolgens terug kunnen brengen naar de bedenkers van TLMO in een request-for-change.

Het gaat om Fysieke integriteit

Dit is een gegevensgroeptype dat bestaat uit drie onderdelen: algoritme, waarde en datum.

algoritme

Er zijn een hoop mogelijke algoritmes om de checksum te bepalen, en er worden voorbeelden gegeven:

• “Longitudinal parity check”
• “Fletcher’s checksum”
• “Cyclic redundancy checks (CRCs)”

Dit is problematisch om een aantal redenen:

• deze lijst is moeilijk te begrijpen voor machines/clients - er is geen exhaustieve lijst van mogelijke algoritmen, dus je kan een algoritme tegenkomen wat je niet ondersteunt (puur omdat je niet wist dat je het zou moeten ondersteunen)

• de waarden zijn in essentie een 'vrij tekstveld'. Ik kan dus naar CRC refereren met de Engelse naam, de Nederlands naam of de afkorting CRC. Dit is veel te vaag in een gegevenslandschap waar machines met machines praten.

Voorstel (dit is hoe ik het ga uitwerken in ZDS 2.0): definieer een enum met de mogelijke algoritmes, gebaseerd op https://en.wikipedia.org/wiki/List_of_hash_functions:

algoritme:
  type: string
  enum:
  - CRC-16
  - CRC-32
  - CRC-64
  - fletcher-4
  - fletcher-8
  - fletcher-16
  - fletcher-32
  - HMAC
  - MD5
  - SHA-1
  - SHA-256
  - SHA-512
  - SHA-3

Deze (initiele) set is op dit moment arbitrair gekozen op wat ik zelf vaak voorbij zie komen - ik heb er geen idee van welke algoritmes op dit moment effectief gebruikt worden binnen Nederland. Het spreekt voor zich dat algoritmes die al in gebruik zijn en ontbreken, aan de lijst zouden moeten toegevoegd worden.

waarde

In het informatiemodel staat beschreven dat de waarde van de checksum numeriek is. Dit valt al uiteen op het moment dat je MD5-checksums gebruikt (komt nog enorm veel voor) - die bevat ook letters.

M.i. moet de waarde dan ook aangepast worden naar alfanumerieke waardes. In de Wikipedia tabel zie ik als maximale lengte 512 bits, in hexadecimale uitwisseling krijg je dan een veld dat maximaal 128 karakters lang is. Dit zou dus maken:

waarde:
    type: string
    minLength: 1
    maxLength: 128

in OpenAPI schema.

API endpoints dienen géén trailing slashes te bevatten

Conclusie uit discussie Geonovum/KP-APIs#8 is om expliciet op te nemen in de guidelines dat API endpoints géén trailing slashes bevatten. Als er wel een trailing slash wordt gebruikt moet dit een 404 Not found teruggeven.

4.9 GeoJSON ondersteunt alleen WGS84

Voor GEO API's wordt bij voorkeur de standaard GeoJSON (RFC-7946) gebruikt.

GeoJSON ondersteunt alleen WGS84:

The coordinate reference system for all GeoJSON coordinates is a geographic coordinate reference system, using the World Geodetic System 1984 (WGS 84) [WGS84] datum, with longitude and latitude units of decimal degrees. (Section 4, see: https://tools.ietf.org/html/rfc7946#section-4)

Deze voorkeur is niet compatible met de voorkeur van het CRS:

7.1.39 API-39: Het voorkeur-coördinatenstelsels (CRS) is ETRS89, maar het CRS wordt niet impliciet geselecteerd

Het lijkt me niet wenselijk dat de voorkeuren elkaar tegenspreken. Verder kan je je vraagtekens zetten bij de waarde van CRS negotiation in combinatie met de GeoJSON voorkeur.

Overweeg strakkere scheiding in HTTP, JSON en REST

De API Designrules beschrijven regels voor HTPP, gebruik van JSON en REST stijl. Overweeg om de gebieden duidelijker van elkaar te scheiden dan nu het geval is. Hierdoor wordt het beter mogelijk om toekomstige ontwikkelingen van de designrules gemakkelijker door te voeren. Een scherpere afbakening maakt hergebruik van delen beter mogelijk: Stel dat JSON op den duur wordt vervangen door een ander formaat of dat een gelijksoortige standaard wel http-verkeer voorschrijft maar een andere vorm van content-interactie dan kunnen wel de regels voor het gebruik van TLS of http-headers gehandhaafd blijven.

De huidige indeling is gebaseerd op functionaliteit. Onderzoek of een indeling per standaard of stijl mogelijk is, bijvoorbeeld
• Eisen op het vlak van HTTP
• Eisen op het vlak van JSON
• Eisen vanwege het gebruik van de REST stijl
• Eisen voor gebruik in de GEO context

Betekenis en gebruik van required properties in PATCH methoden

In de API strategie, maar ook op internet, kon ik niets vinden over het gebruik van required properties bij GET en PATCH methoden, en ik vind de interpretatie van de definitie in JSON Schema Validation geen uitkomst bieden:

6.5.3. required
The value of this keyword MUST be an array. Elements of this array, if any, MUST be strings, and MUST be unique.
An object instance is valid against this keyword if every item in the array is the name of a property in the instance.
Omitting this keyword has the same behavior as an empty array.

Dat een property required is betekent dus dat het niet persé een waarde moet hebben (veel voorkomende misvatting) maar dat het property in het object moet zitten. Zie ook voorbeelden van objects zonder en met required

Neem onderstaande OAS waar een object Quote het required attribuut tekst heeft.

  /quotes/{uuid}:
    get:
      operationId: quote_read
      description: Bekijk een enkele quote.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                required:
                - tekst
                type: object
                properties:
                  tekst:
                    title: Quote
                    type: string
                  bronNaam:
                    title: Bron naam
                    type: string

Aantal vragen hierover:

1. Bij een GET krijg ik dus zeker weten het property tekst terug krijg maar het is niet zeker dat ik bronNaam terug krijg (bijvoorbeeld door compactere versie van een object in lists, of door autorisaties)?
2. Mag je bij een PATCH tekst toch weglaten omdat PATCH sowieso al impliceert dat ik slechts enkele properties wil updaten?
3. Mag je bij een POST bronNaam weglaten, ook al wordt daar (typisch) verwacht dat je de volledige nieuw te maken state meegeeft?
4. Zouden de required properties verschillen tussen al deze methoden, wat impliceert dat we niet makkelijk $ref: '#/components/schemas/Quote' zouden kunnen gebruiken waar een eenduidige definitie staat van het object zodat we het niet bij elke methode inline hoeven te specificeren?

Ruimtelijke operators

In paragraaf 4.9 worden drie ruimtelijke operators genoemd die ondersteund moeten worden: within, contains, en intersects.

De SDWBP noemt meer ruimtelijke operators. Naast de drie al genoemde zijn dit Equals, Disjoint, Touches, Crosses. We kunnen een link naar de SDWBP opnemen hiervoor, dan hoeven we ze niet allemaal te noemen.

Ik zou niet zeggen dat die ondersteund moeten worden maar wel: als je ze ondersteunt, noem ze dan zo.

API Principe 38: GeoJSON niet verplicht stellen

API principe 38 stelt GeoJSON verplicht als formaat.

Hoewel ik het daar in de meeste gevallen helemaal mee eens ben, zijn er helaas situaties waarin GeoJSON niet voldoet. Het ondersteunt bijvoorbeeld niet alle geometrietypen die we mogelijk willen serveren, bijvoorbeeld geen solids en dus geen 3D data.

Ik stel voor om dit te nuanceren (bv toevoegen: tenzij GeoJSON ontoereikend is voor de data die je wilt serveren, zoals…).

Proposal: AP-17 Herformuleren

API-17: Autorisatie is gebaseerd op OAuth 2.0

Het gaat te ver om autorisatie op basis van OAuth 2.0 op landelijk niveau te verplichten. In veel gevallen is OAuth 2.0 te complex. Bovendien is OAuth 2.0 geen authenticatie-service, oftewel gemeentes moeten nog steeds een mechanisme hebben in de (centrale) authenticatie-service om een persoon te kunnen authentiseren met wat de gemeente gebruikt (bijvoorbeeld Active Directory). Indien wel gekozen wordt voor OAuth 2.0 dan worden de OAuth-profielen gevolgd zoals gedefinieerd in de werkgroep Authenticatie Autorisatie

URI strategie genoemd maar niet uitgelegd

In 4.2.7 en 7.1.18 wordt gesproken van een URI-strategie maar deze wordt niet uitgelegd of verwezen. Is dit de URI strategie van de DSO of de algemene URI strategie of moet de NL API strategie ook een URI strategie bevatten?

URIs en de trailing slash ("/")

In ons ZDS-project bij VNG Realisatie eindigen de URIs die gebruikt worden om collecties van objecten of individuele objecten op te vragen nooit met een trailing slash:

Voorbeelden

Goed

• /api/v1/zaken
• /api/v1/zaken?identificatie=12345
• /api/v1/zaken/67890

Fout

• /api/v1/zaken/
• /api/v1/zaken/?identificatie=12345
• /api/v1/zaken/67890/

Rationale
De DSO heeft hier geen expliciet standpunt over maar alle voorbeelden zijn zonder trailing slash. Daarnaast zijn veel commerciele APIs die dit voorbeeld volgen zoals Google en Facebook.

Verschillende bronnen zijn hier wel over verdeeld, zoals
REST API tutorial en Wikipedia maar er is gekozen om te kijken naar de praktijk en DSO.

De vraag is nu welke conventie we moeten volgen in de landelijke API-strategie: altijd een trailing slash, nooit een trailing slash, of beide toestaan?

referentie aanbrengen van 4.3.1 naar H5

4.3.1 schrijft gebruik OAuth voor. zet hier een referentie in naar H5 het Nederlands profiel OAuth

Paginering zonder HAL

In de sectie Paginering van de design rules wordt aangegeven hoe om te gaan met paginering in het geval het mediatype JSON+HAL is. Het zou fijn zijn als we ook weten hoe dat moet in plain JSON. Hieronder een voorstel voor standaardisering van paginering zonder HAL.

{
	"count": 100,
	"page_size": 20,
	"self": "https://.../api/registratie/v1/aanvragen?page=3",
	"first": "https://.../api/registratie/v1/aanvragen",
	"prev": "https://.../api/registratie/v1/aanvragen?page=2",
	"next": "https://.../api/registratie/v1/aanvragen?page=4",
	"last": "https://.../api/registratie/v1/aanvragen?page=5",
	results: [
		{
			"self": "https://.../api/registratie/v1/aanvragen/12",
			"titel": "Mijn dakkapel",
			"samenvatting": "Ik wil een dakkapel bouwen!",
			"aanvrager": "Bob"
		},
		...
	]
}

De velden count en page_size geven informatie over het totale aantal resultaten en het aantal dat per pagina wordt teruggegeven.
De link-namen self, first, prev, next en last zijn gebaseerd op de internetstandaard RFC5988 net zoals HAL dat doet.

4.2.5 expand=true

Ik heb een suggestie voor een verbetering/verduidelijking. In 4.2.5 staat:

Als expand=true wordt meegegeven, dan worden alle geneste resources geladen

Dit snap ik niet, het datamodel is namelijk geen boom (kan cycles bevatten). Daarna staat:

verplicht om te specificeren welke resources en zelfs welke velden van een resource teruggeven moeten worden.

Dit lijkt me in strijd met de eerdere zin (die over expand=true). Wat is de bedoeling hiervan? Kan dit misschien iets duidelijker?

API-10 niet verplichten

Resources ondersteunen "lazy" en "eager" laden van relaties

Dit is een keuze zijn voor de API-designer. Bovendien hoeft het ondersteunen van lazy en eager laden zich niet te beperken tot n-op-n relaties. Indien wel voor dit principe wordt gekozen dan is het gebruik van HAL voor het embedden van relateerde resources niet verplicht en wordt zelfs afgeraden. HAL is een dode standaard die nauwelijks ondersteund wordt in de reguliere programmeeromgevingen van Python, C#, Java, etc. Hal moet geen verplichting zijn, ook plain json moet bijvoorbeeld mogelijk zijn. In ZDS worden relaties met links gelegd. Eager laden gaat mogelijk gemaakt worden met de expand query-parameter, maar zonder HAL-syntax in de payload.

Zie ook #6.

Use clientid as API-key when supporting both API-key & OAuth

When supporting both OAuth and API-key one can re-use the OAuth client -id as an API-key.

Coördinatenstelsel-conversie

Principes API-43 t/m API-45 uit de DSO API Strategie gaan over coördinatenstelsels en mogelijke transformaties. Waar wordt de coördinatenstelsel-conversie gedaan? Client? Service? Moet elke service dat zelf doen ? Kan conversie niet als een externe service aangeroepen worden zodat clients/services simpel blijven?

Conformance endpoint

Is het een idee om net zoals WFS doet een endpoint te hebben waar je informatie over de conformance kan opvragen. Dwz. de conformance van de API ten opzichte van den API strategie.

Externe URIs als waardes

Zie https://github.com/Geonovum/KP-APIs/issues/8#issuecomment-431006149.

API-09 verwijderen

Relaties van geneste resources worden binnen het eindpunt gecreëerd

In ZDS 2.0 hebben geneste resources binnen een andere resource (1-op-n relatie) wel hun eigen eindpunt. Statussen zijn geneste resources van een zaak, maar hebben wel hun eigen endpoint.

Zie ook: https://github.com/VNG-Realisatie/gemma-zaken/blob/eff4d9725e7d93e222d83cd0566674d11aecbcbc/docs/_content/overige/technisch/design-keuzes.md#vertaling-van-relaties

Conventie naamgeving voor API's

In de API strategie staat summier iets over de naamgeving van resources, API-07 en API-08 *).

Conventies voor naamgeving van API's zijn ook nuttig. De eerste vragen hierover dienen zich aan. Is er verschil tussen CRUD data API's en API's die business rules ontsluiten? Hoe zorgen we voor een zekere uniciteit in naamgeving?

*) API-07 Definitie van het koppelvlak is in het Nederlands tenzij er sprake is van een officieel Engelstalig begrippenkader
API-08 Resource namen zijn zelfstandige naamwoorden in het meervoud

Vaste URL voor serveren OAS-schema

Het zou mooi zijn als we een gemeenschappelijke afspraak kunnen maken over op welke URL het OAS-schema geserveerd wordt (faciliteert self-discovering clients). Bijvoorbeeld in dit vaste formaat:

https://.../.../api//schema/openapi.yaml

Voor het opvragen van het schema van onze API voor de zaakregistratiecomponent (zrc) ziet de URL er zo uit: https://ref.tst.vng.cloud/zrc/api/v1/schema/openapi.yaml

Proposal: API-42 verduidelijken

Resultaten van een globale geometrische zoekvraag worden in de relevante geometrische context geplaatst

Dit principe is niet duidelijk en zou beter moeten worden uitgelegd in de tekst van sectie Geo-ondersteuning

Proposal: validatiefouten bij geneste datastructuren

In de DSO API strategie wordt al aangegeven om validatiefouten per veld op te nemen onder een key invalid-param. Op het forum had ik hier al enkele opmerkingen over geplaatst.

Nu loop ik tegen een geneste datastructuur aan die gepost kan worden:

{
    "identificatie": "",
    "integriteit": {
        "algoritme": null,
        "waarde": "",
        "datum": null
    }
}

Doordat invalid-params een lijst is, kan die genestheid niet zomaar overgenomen worden. Mijn voorstel is dan ook om de genestheid uit te drukken met een . als scheiding:

{
    "type": "http://localhost:8000/ref/fouten/ValidationError/",
    "code": "invalid",
    "title": "Invalid input.",
    "status": 400,
    "detail": "",
    "instance": "urn:uuid:60364d74-1117-41eb-88f0-4dd3c90a0ed2",
    "invalid-params": [
        {
            "name": "integriteit.algoritme",
            "code": "null",
            "reason": "Dit veld mag niet leeg zijn."
        },
        {
            "name": "integriteit.waarde",
            "code": "blank",
            "reason": "Dit veld mag niet leeg zijn."
        },
        {
            "name": "integriteit.datum",
            "code": "null",
            "reason": "Dit veld mag niet leeg zijn."
        }
    ]
}

editorials

• API principes kunnen we markeren als een best practice, dan kun je voorin het doc ook ergens een summary van alle principes zetten. Net zoals in de SDWBP.
• Hier en daar zie je de DSO bias, niet alleen doordat DSO expliciet genoemd wordt, maar ook in functionaliteit die specifiek in de juridische context van de DSO belangrijjk is. Bv het stuk over tijdreizen. Zoek op ‘juridisch’ en overweeg dit eruit te halen.
• De stukken voorbeeldcode in een
  zetten.

6.1.12 moet geschrapt worden!

6.1.12 API-12: API's zijn bij voorkeur alleen bruikbaar met behulp van een API-key

Voor alle API's wordt bij voorkeur minimaal een registratie inclusief acceptatie van de fair use voorwaarden vereist. Op basis hiervan zal dan een API-key wordt uitgegeven.

Dit is een punt dat geschrapt moet worden, of omgekeerd. Er moet zakelijke reden zijn, alvorens Api keys noodzakelijk gesteld worden.

6.1.17 #17 Documentatie in het Nederlands

Omschrijving is vaag: "…[tenzij] er sprake is van een officieel Engelstalig begrippenkader". Engels is de voertaal voor vrijwel alle internationale standaarden of stijlbeschrijvingen. “API” zelf is al een Engelstalig begrip. Het OAUTH profiel is in het Engels gesteld. Was dat vanwege bestaande documentatie of het Engelstalige begrippenkader? Er is ook een praktisch bezwaar: Veel ontwikkelaars in Nederland hebben een niet Nederlandstalige achtergrond, maar worden wel geacht APi’s te ontwikkelingen voor Nederlandse voorzieningen. Bij Digikoppeling is voor het ebMS profiel een Engelstalige template (sorry, sjabloon) gebruikt. Hierdoor is het normatieve gedeelte van ebMS in het Engels gesteld.
Overweeg om voor niet-normatieve beschrijvingen Nederlands als voorkeurstaal in te stellen en om voor het normatieve gedeelte Engels te gebruiken. Maar ben hier ook niet helemaal zeker over.

Proposal: API-39 verduidelijken

GeoJSON is onderdeel van de embedded resource in de JSON respons

Dit principe is niet helder. Graag een voorbeeld opnemen om het te verduidelijken.

De juiste bibliografische referentie voor HAL

In API principe 46 wordt verwezen naar RFC4627 voor HAL. RFC4627 is volgens Specref obsolete. In paragraaf 4.2.5 staat voor HAL een verwijzing naar http://stateless.co/hal_specification.html. Welke is beter?

Gebruik van HATEOAS

De DSO API Strategie gebruikt een uitgeklede versie van HAL om navigatie binnen de API mogelijk te maken. De vraag is of dit de beste keuze is en hoe ver we hier in moeten gaan. Wat zijn mogelijke alternatieven en wat is de impact daarvan?

API-keywords zoals 'sorteer' en 'zoek' moeten ALTIJD in het Engels

Zie secties 4.7.2 en 4.7.3. Voorstel: Vervang 'sorteer' door 'sort en 'zoek' door 'search'.

Onderbouwing van sommige regels is onvoldoende of ontbreekt.

Hoewel sommige regels obvious lijken, bijvoorbeeld omdat 'iedereen er mee werkt', is het vanuit een beheerperspectief raadzaam om alle regels zoveel mogelijk te onderbouwen. We hebben bij het beheer een ander afsprakenset (Digikoppeling, iets met XML en SOAP ) gemerkt dat wanneer we regels willen aanpassen vanwege nieuwe wensen of voortschrijdend inzicht, vrijwel altijd eerst de motivatie voor de oude regel opzoeken -of proberen te achterhalen. Met motivatie boven water kan de impact van het aanpassen van een regel vaak beter worden ingeschat.

We missen in ieder geval onderbouwing bij regels: #3, #11, #15, Geonovum/KP-APIs#19, #23, Geonovum/KP-APIs#28, Geonovum/KP-APIs#29, Geonovum/KP-APIs#42, Geonovum/KP-APIs#48, Geonovum/KP-APIs#5 en #49. Over een aantal regels loopt nu nog discussie Als we eruit zijn, kunnen we dat mooi gebruiken voor een nadere onderbouwing.

Voor aantal van de genoemde regels heb ik een aparte issue aangemaakt.

Proposal: AP-12 herformuleren

Representatie op maat wordt ondersteund

Niet verplicht om de representatie op maat te ondersteunen. Als het wel wordt ondersteund, dan wel volgens de eisen van dit principe.

Specificatie van geoJSON

In schemas.yaml zit nu een specificatie van een GeoJsonObject.
Voor VNG-Realisatie/gemma-zaken is een meer gedetailleerde uitwerking gemaakt. Wellicht kunnen we die overnemen?

Constructie voor mogelijk gedeeltelijk onbekende datum

In sommige registraties is het mogelijk dat een datum slechts gedeeltelijk bekend is. Bijvoorbeeld wanneer we van een persoon alleen weten in welk jaar deze geboren is. Of dat alleen het jaar en de maand van de geboortedatum bekend is.

Overweging hierbij is dat:

• Dit soms voorkomt en een valide situatie is. Dit moet worden teruggeven in het antwoord.
• Het grootste deel van de datums wel volledig zijn. De oplossing moet het gebruik van de datum voor deze bulk van situaties niet (teveel) compliceren.

Wij (project voor API bevragingen ingeschreven personen) zijn hier tot de conclusie gekomen dat dit op de volgende manier handig is om op te nemen.
Wanneer volledige datum bekend is:

"geboortedatum": {
      "datum": "1973-11-27",
      "jaar": "1973,
      "maand": "11",
      "dag": "27"
    }

Wanneer alleen jaar en maand bekend is:

"geboortedatum": {
      "jaar": "1973,
      "maand": "11"
    }

Ik wil voorstellen de api definitie hiervan ook op te nemen in schemas.yaml

    Datum_onvolledig:
      type: "object"
      properties:
        datum:
          type: "string"
          title: "datum"
          format: "date"
          description: "De volledige datum die in de `date` definitie past. Dit element wordt alleen gevuld als de volledige datum bekend is."
        jaar:
          type: "string"
          title: "jaar"
          description: "Het jaar van de datum. Als het jaar bekend is wordt dit element gevuld, ook als de volledige datum bekend is."
          format: "date_fullyear"
          pattern: "^[1-2]{1}[0-9]{3}$"
        maand:
          type: "string"
          title: "maand"
          description: "De maand. Als de maand van een datum bekend is wordt dee hier ingeveuld. Ook als de volledige datum is ingevuld."
          format: "date_month"
          pattern: "^99$"
          maxLength: 2
        dag:
          type: "string"
          title: "dag"
          description: "De dag. Als de dag van de datum bekend is wordt deze hier ingevuld. Ook als de volledige datum bekend is."
          format: "date_mday"
          pattern: "^99$"
          maxLength: 2

N.B. besproken alternatieven:

1. Datum plus precisie

"geboortedatum": {
      "datum": "1973-01-01",
      "precisie": "jaar"
    }

Nadeel: de waarde van de datum kan een fictieve waarden hebben. Slordig gebruik van deze datum door consumer (niet raadplegen precisie) kan tot verkeerde interpretatie leiden.

2. Datum als oneOf date, jaar, jaarmaand

"geboortedatum": "1973-11-23"
"geboortedatum": "1973-11"
"geboortedatum": "1973"

Nadeel: datum kan niet direct gebruikt worden als date, waarmee gerekend kan worden. Consumer moet dit zelf afleiden.

3. Datum als lossen velden jaar, maand, dag

"geboortedatum": {
      "jaar": "1973,
      "maand": "11",
      "dag": "27"
    }

Nadeel: datum kan niet direct gebruikt worden als date, waarmee gerekend kan worden. Consumer moet dit zelf afleiden.

Links tussen verschillende API's

Met HATEOAS kunnen we navigeren binnen API's. Door absolute URL's in plaats van relatieve URL's te gebruiken kunnen we ook linken naar andere API's (bijv. van een BAG pand bag.basisregistraties.overheid.nl/api/v1/panden/123 naar een BRK perceel brk.basisregistraties.overheid.nl/v1/percelen/234).

Echter, wat gebeurt er als de URL structuur van een van de API's verandert? In het voorbeeld zou de BRK een v2 kunnen lanceren waardoor de URL verandert naar brk.basisregistraties.overheid.nl/v2/percelen/234. Bovendien hoeft een nieuwe major versie als deze niet backwards compatible te zijn, dus ook de inhoud van de API responses kan anders zijn. Clients die beide API's bevragen en de 'convenience' link van de BAG naar de BRK gebruiken kunnen hierdoor in de problemen komen.

Een mogelijke oplossing kan zijn om de versie van de API waarnaar gelinkt wordt expliciet op te nemen in het link object naar de API, waarbij de beschikbaarheid van de links gelijk loopt met de beschikbare versies van die API bijvoorbeeld:

_links: {
  brkPerceelV1: {
    href: 'https://brk.basisregistraties.overheid.nl/v1/percelen/234'
  },
  brkPerceelV2: {
    href: 'https://brk.basisregistraties.overheid.nl/v2/percelen/234'
  },
}

Hierover moeten wel afspraken gemaakt worden, bijvoorbeeld dat de link naar v2 wordt toegevoegd zo snel mogelijk nadat v2 gereleased is, en dat de link naar v1 wordt weggehaald op het moment (of zo kort mogelijk daarvoor) dat v1 uit de lucht wordt gehaald.

CRS content negotiation

@dvh @jasperroes Voor de zekerheid een controle vraag over de interpretatie van de principes API-43 t/m API-45 over CRS content negotiation uit de DSO API Strategie. Kunnen de Accept-Crs/Content-Crs headers weggelaten worden als de request/response bodies geen geo-data bevatten?

Don't mix Caching and Conditional requests in API principles

I expect

etags and RFC7232 to be about conditional requests and incidentally caching

HTTP RFC: Caching to be about Caching.

@dvh

See review in #26_

API-48 verwijderen

Beperken van het aantal verzoeken per tijdsperiode wordt centraal opgelost door het Stelselknooppunt

Nog niet bekend of en via welk knooppunt dit in de Common Ground geregeld gaat worden. Wellicht decentraaal via de NLX door middel van configuratie van de In- of Outway. Nog niet bekend of en via welk knooppunt ZDS API's worden aangeboden. DSO specifiek.

API-05 verwijderen

Communicatie met API’s verloopt alleen via het Stelselknooppunt

Dit principe is te specifiek voor DSO. Gemeentelijke API's zullen doorgaans worden aangeboden via NLX en niet alleen via het Stelselknooppunt. Het Stelselknooppunt is alleen bedoeld voor de API's t.b.v. de Omgevingswet. ZDS 2.0 wordt breder ingezet.

6.1.11 verbinding is altijd versleuteld met TLSv1.2. Welke verbinding? met wie?

Dit principe gebruikt de term: “de verbinding” maar vermeldt niet tussen welke partijen de verbinding is gelegd. Gaat het altijd om verbinding met "derden"? Gaat het om twee organisaties gescheiden door een extern netwerk zoals Diginetwerk of Internet? Is het raadzaam om transportbeveiliging obv TLSv1.2 ook toe te passen op intern verkeer?

Vermijd verwarring door deze regel aan te scherpen.

Gebruik fields parameter: wat betekent

In de API Strategie staat in de tekst boven (bij) API-12:

In het geval van HAL zijn de gelinkte resources embedded in de standaard representatie. Met de hier beschreven fields parameter ontstaat de mogelijkheid om de inhoud van de body naar behoefte aan te passen.

Wat betekent dit? Worden relaties in _links die in het antwoord teruggegeven worden beïnvloed door de fields parameter?
Wanneer ik bijvoorbeeld bij het bevragen van een persoon "fields=burgerservicenummer, naam" gebruik, krijg ik dan in _links toch de partners, ouders en kinderen van de persoon?
Of kan ik alleen de links naar de kinderen krijgen via "fields=kinderen"?

API-44: Beperken van het aantal verzoeken per tijdsperiode wordt aangeraden

Regel is een advies. De tekst beschrijft hoe je de load kan inperken maar de regel vermeldt het gebruik van de X-RATE headers niet. Het advies zou ik in een best practice opnemen. Van de manier waarop je het moet doen zou ik een regel maken.

Voorstel voor verbetering
Gebruik X-RATE headers voor het beperken van het aantal verzoeken

Geen gedetailleerde geometrieën vereisen in brondata

In paragraaf 4.9 staat bij geo ondersteuning:

het is wel belangrijk dat dit antwoord juist is, en de brondata dus zeer gedetailleerde geometrieën bevat

Dat is echter afhankelijk van de use case en kan je dus in een algemene API strategie niet stellen, zoals gesteld in Spatial Data on the Web best practice 7.

Bovendien te simpel gesteld: vaak zal de locatiebepaling van de (gps) device van de vraagsteller niet zo nauwkeurig zijn, en dan helpen gedetailleerde geometrieen niet echt.

Ik stel voor om deze zin te verwijderen.

API principes 15 en 21 niet verplichten of generieker formuleren

• Een aantal api principes uit hfd 7 lijken DSO specifiek
  • principe 15
  • principe 21
  • anderen zijn al genoemd in aparte issues.

Mijn voorstel is om deze of te verwijderen of generieker te formuleren.