notificaties_create status

[Dadinos]

Het notificaties_create endpoint is een POST endpoint en maakt een nieuwe notificatie aan.
Normaal zou je hier een status 201 voor moeten retourneren waarom is het hier een status 200?

Of is dit een fout in de beschrijving.

Tevens werken de redoc endpoints niet:
https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/VNG-Realisatie/notificaties-api/master/src/openapi.yaml

[sergei-maertens]

edit: verwarring met webhook consumer...

semantisch is 2xx m.i. hier correct, omdat ook een HTTP 202 ook valide is in het geval dit asynchroon verwerkt wordt. Ook een HTTP 204 kan, er is namelijk niets opgelegd aan wat er als response body terug moet keren en de notificatieservice moet enkel weten of de notificatie correct bij de consumer bezorgd is of niet.

Een HTTP 201 impliceert dat er een resource aangemaakt is die ook weer op te halen is, maar er is geen garantie (of uberhaupt gedefinieerd gedrag) over het ophalen van een gepubliceerde notificatie, dus er is ook geen wel-gedefinieerd gedrag over de Location header die typisch bij een 201 voorkomt. In dat opzicht is een generieke HTTP 200 beter geschikt dan een HTTP 201.

[Dadinos]

Ook een HTTP 204 kan, er is namelijk niets opgelegd aan wat er als response body terug moet keren en de notificatieservice moet enkel weten of de notificatie correct bij de consumer bezorgd is of niet.

Als response body lees ik dat dit terug moet komen:

{
  "kanaal": "string",
  "hoofdObject": "http://example.com",
  "resource": "string",
  "resourceUrl": "http://example.com",
  "actie": "string",
  "aanmaakdatum": "2022-11-15T11:48:44Z",
  "kenmerken": {
    "property1": "string",
    "property2": "string"
  }
}

En hieruit: https://vng-realisatie.github.io/gemma-zaken/themas/achtergronddocumentatie/notificaties

Notificaties ophalen (CONCEPT)
In eerste instantie zetten we enkel in op push via webhooks. Later laten we toe om ook notificaties te pullen.

GET /api/v1/abonnementen/ae54ef/notificaties HTTP/1.0

Authorization: Bearer abcdef1234
Accept: application/json

[{
    "kanaal": "zaken",
    "hoofdObject": "https://zaken-api.vng.cloud/api/v1/zaken/d7a22",
    "resource": "status",
    "resourceUrl": "https://zaken-api.vng.cloud/api/v1/statussen/d7a22/721c9",
    "actie": "create",
    "aanmaakdatum": "2018-01-01T17:00:00Z",
    "kenmerken": {
        "bron": "082096752011",
        "zaaktype": "https://example.com/api/v1/zaaktypen/5aa5c",
        "vertrouwelijkeidaanduiding": "openbaar"
    }
}]

Dit zal enkel de niet bezorgde notificaties teruggeven.
Dus naar mijn idee, en omdat ook alle andere post / create een 201 teruggeven, lijkt mij dat juist consequenter en logischer om daar niet van af te wijken.

[sergei-maertens]

ik was in de war met de response van de webhook ontvanger over de response body, my bad! de notificaties API zelf geeft idd wel een body terug (wat niet anders is dan de input data) en zou consistenter zijn als het een HTTP 201 is.

In eerste instantie zetten we enkel in op push via webhooks. Later laten we toe om ook notificaties te pullen.

Ja, dat was het plan, maar dat is een stille dood gestorven...

Als ik verder MDN nalees over HTP 201 (https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201) dan lees ik wel de eis dat de resource location gecommuniceerd moet worden waarbij de Location header optioneel is in dit geval omdat de resource in de response body teruggegeven wordt.