Onduidelijkheid gebruik HAL in de API-strategie

Organisaties Digitaal Stelsel Omgevingswet
#1

De API-strategie noemt het gebruik van van HAL maar is vrij onduidelijk. Er staat o.a.:

“Voor paginering wordt aangesloten op Hypertext Application Language (HAL). […] API-46 Paginering wordt gerealiseerd op basis van JSON+HAL” (API-strategie v1, pagina 29/30)

Vraag 1 Betekent dit nu dat HAL alleen wordt gebruikt voor list resources waar paginering wordt gebruikt, of alle list resources (dus ook zonder paginering)? Ook lijkt het vreemd dat HAL alleen toegepast wordt voor list resources, en niet voor alle resources.

“Indien het “plain” JSON, GeoJSON of iets anders dan HAL betreft zijn er geen _links. Deze kunnen dan opgenomen worden in de link response headers.” (API-strategie v1, pagina 30)

Vraag 2 Mag je dus list resources ook opvragen als “plain” JSON, en niet alleen als HAL+JSON?

Vraag 3 En wat wordt er bedoeld met de “link response headers”?

#2

@tessa @dvh kunnen jullie reageren?

#3

Als je application/hal+json opvraagt krijg je de HAL+JSON response. Dit geldt voor alle resources, niet alleen voor list resources. Paginering is een onderdeel van HAL.

Als je ook application/json of application/geo+json responses wil ondersteunen dan ben je vrij om dat te doen. De _links die nodig zijn om bijvoorbeeld te pagineren kun je dan opnemen in de Link response header:

Link: <https://api/collectie?page=2>; rel="next", <https://api/collectie>; rel="self"

#4

Bedankt voor je antwoord @dvh. Dat is helder.

Het stuk hierover in het API strategie document kan wellicht iets duidelijker. Het lijkt nu een verplichting om (alleen) list/gepagineerde responses via application/hal+json te serveren maar het is dus slechts een mogelijkheid. Paginering kan dus ook prima met application/json.

Wellicht moet HAL aan het begin genoemd worden in plaats van onder paginering.

1 like
#5

Ik neem het mee!