API kwaliteitscriteria

Laatst bewerkt: 6 januari 2022, 17:21:59

API-specificaties welke een werkgroep oplevert dienen te voldoen aan onderstaande API kwaliteitscriteria.

Toepassing van deze kwaliteitscriteria is op basis van ‘pas toe of leg uit’: verplicht gebruik tenzij toepassing niet mogelijk of zinvol is, danwel gemotiveerd anders is ingevuld / opgelost.

Kwaliteitscriteria voor release candidates en definitieve versies van API-specificaties zijn:

  • De specificatie bevat een globale functionele beschrijving (samenvatting) van de standaard
  • De specificatie bevat een beschrijving van het toepassingsgebied
  • Beschreven is hoe de standaard past binnen de GEMMA
  • API interactiepatronen zijn beschreven
  • De specificatie bevat een beschrijving van het gedrag van de API. Waar nodig worden er zowel voor consumer als voor provider aanvullende specificaties in proza of feature-beschrijvingen.
  • De specificatie bevat een beschrijving van functionaliteiten
  • De specificatie bevat verwijzingen naar de informatiemodellen behorend bij de API-standaard:
    • een semantisch informatiemodel / catalogus/ logisch ontwerp waar de semantiek voor deze standaard is beschreven.
    • Indien beschikbaar: een conceptueel informatiemodel (CIM)
    • Indien beschikbaar: uitwisselingsgegevensmodel (UGM)
  • De specificatie bevat concrete voorbeelden welke gebruik van de API illustreren (berichten / JSON)
  • De specificatie voldoet aan de Nederlandse API Strategie
  • De specificatie voldoet aan de REST-API Design Rules van de Nederlandse API Strategie
  • De specificatie voldoet aan de VNG-R Best Practices: VNGR- Design Rules Policy, Design Rules
  • Technische specificaties zijn opgesteld in OpenAPI Specification 3.0.x in overeenstemming met de Nederlandse API Strategie
  • Beschreven zijn welke delen, operaties, aspecten verplicht dan wel optioneel geïmplementeerd moeten zijn om compliant aan de standaard te zijn. Zover mogelijk wordt dit in de technische documentatie (OAS3) opgenomen. Waar dat niet kan wordt in proza beschreven wat de Provider verplicht dient aan te bieden.
  • Een verplichte sectie ‘Beveiligings- en Privacy overwegingen’ is opgenomen in de specificatie. In deze sectie zijn voor de standaard relevante beveiligings- en privacy overwegingen geadresseerd, zoals duiding van bekende kwetsbaarheden, mogelijke bedreigingen en mechanismen of strategieën om deze aan te pakken worden beschreven.