Richtlijnen afleverbetrouwbaarheid Notificaties

Deze pagina is onderdeel van de Architectuur Notificeren in het Federatief Datastelsel. Voor het borgen van betrouwbaarheid bij het gebruik van REST API's moeten extra maatregelen worden genomen om deze op een soortgelijk niveau als ebMS te krijgen. Geonovum heeft een document geschreven waarin zij uitgebreid ingaan op het creëren van een hoger betrouwbaarheidsniveau voor API's. In deze architectuur is een vertaling gemaakt naar richtlijnen voor het creëren van afleverbetrouwbaarheid voor notificaties via API's. Daarbij wordt een onderscheid gemaakt tussen een standaard betrouwbaarheidsniveau dat eenvoudig te implementeren is, en een hoger betrouwbaarheidsniveau voor gevallen waarin dat nodig is voor het specifieke gebruik.

Uitgangspunten bij deze richtlijnen zijn:

Informatie-arme notificaties, met raadpleging door consumer na notificatie
At-least-once aflevergarantie met idempotentie
Gebruik van REST API’s, eventueel in combinatie met Webhooks
Gebruik van de Federated Service Connectivity standaard

De richtlijnen voor de standaard afleverbetrouwbaarheid zijn:

Producers maken kenbaar welke afleverbetrouwbaarheidsniveaus worden ondersteund
Producers registreren de status van verzending en ontvangst van notificaties
Consumers geven een bevestiging van ontvangst (HTTP 200) als zij voldoende zekerheid hebben dat verdere verwerking is gegarandeerd
Producers voorzien notificaties van een speciale header (Idempotency-Key) waarmee consumers duplicaten van notificaties kunnen afhandelen
Producers proberen een notifcatie een beperkt aantal keer te verzenden als deze niet afgeleverd kon worden
Consumers zijn zelf verantwoordelijk voor het raadplegen van gebeurtenissen waarover notificaties gemist zijn
Producers bieden een API voor het raadplegen van gebeurtenissen, ook vanaf een specifiek moment in tijd
Producers zetten het versienummer van het gebruikte schema in de notificatie
Producers hanteren semantic versioning voor schema's
Producers maken kenbaar hoe ze omgaan met wijzigingsbeheer en versionering
Producers maken de verwachte volumes van notificaties kenbaar
Als volgorde van notificaties belangrijk is dan voorzien producers de notificaties van de sequence eigenschap

De richtlijnen voor de hoge afleverbetrouwbaarheid zijn:

Producers gebruiken een exponential backoff voor herverzending van notificaties die niet afgeleverd konden worden
Producers maken het mogelijk om afspraken te maken over het aantal keer en de duur van herverzendpogingen
Producers nemen contact op met consumers via een alternatief kanaal (bijv. email) als notificaties niet afgeleverd konden worden of als consumers een schemavalidatiefout rapporteren
Consumers geven aan als zij een notificatie nog niet kunnen verwerken vanwege capaciteitsproblemen (HTTP 429) en na hoeveel tijd een producer het opnieuw moet proberen (via de Retry-After header)
Producers respecteren indicaties van consumers dat zij een notificatie nog niet kunnen verwerken en bufferen notificaties in de tussentijd
Producers maken het mogelijk voor consumers om aan te geven met welke snelheid zij notificaties kunnen verwerken
Producers maken gebruik van JAdES signing van notificaties als er eisen worden gesteld aan onweerlegbaarheid van notificaties

Er zal binnen het kennisplatform API's een nadere uitwerking plaatsvinden van deze richtlijnen.