search

melsk-r / HC-common-issues

0 stars 0 forks source link

Fields parameter i.cm. templated links issue #16

Closed melsk-r closed 4 months ago

melsk-r commented 4 months ago

Originally created by strijm (https://github.com/VNG-Realisatie/Haal-Centraal-common/issues/55):

Uit de uri-templating feature lees ik dat als er met een fields parameter op _links wordt gefilterd maar niet op de property (array) die identificaties bevat die ingevuld kunnen worden in een templated link. De lijst altijd geleverd moet worden.

Mijn conclusie is dan, dat er altijd maar één link is en dat het dus niet nodig is om een array van links te hebben.

Bv. de BAG panden links ziet er nu als volgt uit:

Pand_links:
  type: object
  properties:
    self:
      $ref: 'https://raw.githubusercontent.com/VNG-Realisatie/Haal-Centraal-common/v1.0.0/api-specificatie/common.yaml#/components/schemas/HalLink'
    adressen:
      type: array
      items:
        $ref: 'https://raw.githubusercontent.com/VNG-Realisatie/Haal-Centraal-common/v1.0.0/api-specificatie/common.yaml#/components/schemas/HalLink'
    adresseerbareObjecten:
      type: array
      items:
        $ref: 'https://raw.githubusercontent.com/VNG-Realisatie/Haal-Centraal-common/v1.0.0/api-specificatie/common.yaml#/components/schemas/HalLink'

Maar doordat er gebruik wordt gemaakt van URI templates, is er maar één link nodig, dus hoeft er onder adressen en adresserbareObjecten geen array maar één enkele link te staan. Als dit het geval is, moet dan de BAG OAS specificatie hierop aangepast worden?

melsk-r commented 4 months ago

This comment originally might have been created by someone else.

het idee is dat je als provider HAL links levert en zelf kan bepalen of je die templated levert of niet. De keuze daarvoor wordt bijvoorbeeld bepaald door het aan tal links dat je moet leveren. Bijvoorbeeld een pand met heel veel adressen (flatgebouw) zou je alle nummeraanduidingIdentificaties moeten opnemen en evenveel _links.adressen. Dan kan je ervoor kiezen deze templated aan te bieden. Door deze link te definiëren als enkele link i.p.v. array wordt je verplicht het templated aan te bieden en kan je niet meer kiezen het nu of in de toekomst als gewone link aan te bieden. De gekozen constructie biedt dus het meeste flexibiliteit voor de aanbieder.

De feature die je noemt zegt dus ook niet dat je dit soort links templates moet aanbieden, maar dat wanneer je een link templated aanbiedt, je bij gebruik van fields de link en de gebruikte identificatie-property aan elkaar moet koppelen.