Gebruik van HATEOAS about kp-apis HOT 12 CLOSED

Nadeel van HAL is dat het een "dode standaard" is. Geen community die het onderhoudt, en in onvolwassen status volgens mij.

Ook in ons scrum team punt van aandacht, zie o.a. VNG-Realisatie/gemma-zaken#216

from kp-apis.

OAS 3 maakt het mogelijk om links op te nemen in de specificatie, waarmee een deel van HAL overbodig wordt.

Verder verdwijnen URLs uit je berichten, en staan ze alleen nog maar in de specificatie. Kort door de bocht, in plaats van (indien HAL, binnen het _links object van de response):

"zaaktype": "https://ztc.vng.nl/api/v1/zaaktypen/12345"

wordt het (in het object zelf, met een operationRef in de OAS):

"zaaktype": "12345"

Waarbij in OAS staat hoe je deze identifier gebruikt om bij de resource te komen (de URL template zeg maar ~ operationRef). Lijkt me erg netjes maar in de praktijk nog geen ervaring mee opgedaan.

Goede uitleg op: https://swagger.io/docs/specification/links/

from kp-apis.

@joeribekker zoals je aangeeft zijn OAS links bedoeld om relaties binnen de spec te definiëren, zodat tooling (bijv. documentatie) hier iets mee kan (bijv. deze relaties weergeven). Dit gaat niet over de daadwerkelijke responses van de API, waardoor een machine niet kan navigeren. Hier heb je URLs voor nodig in je response. Een manier om die URLs erin te zetten is HAL. Ik hoor graag goede alternatieven, maar OAS links zijn een alternatief voor "we zetten helemaal geen URLs in de responses", en dat lijkt me een hele andere discussie. (die hier uiteraard prima gevoerd kan worden, maar dan bedoelen we in ieder geval hetzelfde ;-))

from kp-apis.

Sorry, foutje!

from kp-apis.

Nadeel van HAL is dat het een "dode standaard" is. Geen community die het onderhoudt, en in onvolwassen status volgens mij.

Eens, maar ik vraag mij af in hoeverre dit een daadwerkelijk nadeel is. Het is enkel een manier om iets op te schrijven. In ons geval hebben we gezegd dat we _links en _embedded een goede (en eenvoudige!) manier vinden om een onderscheid te maken tussen de data zelf en hypermedia controls om binnen de API automatisch te kunnen navigeren. De enige HATEOAS variant die wel stable is en onderhouden wordt is volgens mij apis.json, maar dit is gelijk weer van een hele andere orde. Ik zou het overigens persoonlijk mooi vinden als we dat volledig gaan ondersteunen, maar vanuit het oogpunt dat de hele overstap naar REST API's an sich al een hele uitdaging blijkt ben ik allang blij met een paar 'geleende' eigenschappen van HAL ;-)

from kp-apis.

M.i. is het probleem met _links dat het ook in geneste objecten voorkomt. In de praktijk merken we dat clients wel referenties naar (dezelfde) objecten makkelijk willen kunnen resolven, en dan komen dezelfde objecten/referenties in een top-level object terug (_includes bijvoorbeeld), wat repetition weghaalt.

Voor ons (ik ben ook bij het ZDS project betrokken) is eigenlijk voor ons het uitgangspunt nu:

• de OAS spec beschrijft dat een een property een URL is (via de format: uri schema key), dus clients zouden moeten de OAS spec consumen om deze links te kunnen volgen
• het extracten van de links server-side om ze onder de 'arbitraire' key _links te plaatsen is... vervelend. De responses moeten omgeschreven worden, terwijl we wegens het vorige punt er niet meteen wat mee winnen.

Er zijn al best een aantal pogingen geweest om dit de standaardiseren, zij het met HAL, zij het met json-schema... maar ik heb de indruk dat er niet 1 iets is dat echt kan overtuigen. Dat geeft me ook een beetje het gevoel dat er niet echt een sterke noodzaak aan is - als er voldoende vragende partij zou zijn, dan zou dit waarschijnlijk al langer generiek opgelost zijn 😉

from kp-apis.

zoals je aangeeft zijn OAS links bedoeld om relaties binnen de spec te definiëren, zodat tooling (bijv. documentatie) hier iets mee kan (bijv. deze relaties weergeven). Dit gaat niet over de daadwerkelijke responses van de API, waardoor een machine niet kan navigeren. Hier heb je URLs voor nodig in je response.

Volgens mij wordt juist expliciet aangegeven dat het voor paginering gebruikt kan worden en een machine hiermee wel kan navigeren. Even met het handje snel een voorbeeldje gemaakt:

paths:
  /users:
    get:
      operationId: users_list
      parameters:
        - in: query
          name: page  # <-- paginering query parameter
          schema:
            type: integer
            format: int64
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:  # <-- paginering navigatie
                    type: object
                    properties:
                      previous:    # <-- vorige
                        type: integer
                        format: int64
                      next:
                        type: integer  # <-- volgende
                        format: int64
                  id:
                    type: integer
                    format: int64
                  name:
                    type: string
          links:  # <-- instructies om van de metadata een volwaardige URL te maken
            previous:
              operationId: users_list
              parameters:
                page: '$response.body#/metadata/previous'
            next:
              operationId: users_list
              parameters:
                page: '$response.body#/metadata/next'

GET /users

HTTP 200
{
  "metadata": {
    "previous": null,
    "next": 2,
  },
  "id": 615816,
  "name": "John Doe"
}

Met behulp van de OAS (toegegeven, aan het response alleen heb je niet genoeg) kan een machine nu prima vinden dat als je naar de volgende pagina wilt (middels de next link), je naar de URL /users/?page=2 moet gaan.

from kp-apis.

OAS bemoeit zich niet met met de inhoud van de API. metadata kan net zo goed _links of blaat heten, met de OAS links geef je aan hoe die relaties onderling in de API in elkaar zitten. Dit kun je vervolgens gebruiken om tools te genereren (en ja, evt. ook server/client code die op basis daarvan kan gaan pagineren), maar je kunt er niet vanuit gaan dat elke client de OAS gaat consumeren. Met andere woorden, de API beschrijft zichzelf dan niet meer, en daarmee gebruik je dus geen hypermedia.

"The concept of links is somewhat similar to hypermedia".

In het voorbeeld van @joeribekker gebruiken we een eigen variant, namelijk metadata om hypermedia in de response te krijgen; dan kun je m.i. net zo goed iets gebruiken wat breder geadopteerd is. Maar ik begrijp van @sergei-maertens dat dit dus eigenlijk ook niet wenselijk is, want dan wordt het onderdeel van de resources.

Enfin, het is denk ik wel belangrijk om helder te hebben wat de rollen van OAS en de API zijn. Ik zou zeggen: ja, we voegen Links objecten in de OAS toe, maar dit zouden we sowieso moeten doen om de relaties tussen met de HAL objecten te omschrijven. Het is geen vervanging voor HAL of een andere vorm van hypermedia.

from kp-apis.

Als werkgroep komen we nu niet tot een conclusie, dit punt moeten we later nog een keer bespreken.

from kp-apis.

#108

from kp-apis.

Als alternatief voor HAL zou ook gekeken kunnen worden naar JSON:API (https://github.com/json-api/json-api). Deze wordt in ieder geval met (iets) meer regelmaat bijgewerkt.

from kp-apis.

De hypermedia extensie, waarin deze zaken zijn verwerkt, is inmiddels vastgesteld. Voor nieuwe punten kan een nieuw issue worden opgevoerd.

from kp-apis.