self link in collectie moet niet de fields parameter bevatten
Closed this issue · 9 comments
Bijvoorbeeld bij /wozobjecten?kvkNummer=00409420&fields=waarden,belanghebbendeEigenaar.naam
Verwacht ik in _links.self.href de query parameters incl. fields: "https://api.acceptatie.kadaster.nl/lvwoz/api/v1/wozobjecten?kvkNummer=00409420&fields=waarden,belanghebbendeEigenaar.naam"
Maar verwacht ik in _embedded.wozObjecten[0]._links.self.href geen query parameters, dus ook geen fields: "https://api.acceptatie.kadaster.nl/lvwoz/api/v1/wozobjecten/000500030831"
Zie https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/master/features/self-links.feature
Als een search query een fields parameter bevat worden de velden in de embedded wozObjecten gefilterd. Wanneer de self link vervolgens geen fields parameter bevat, levert deze link niet het zelfde object dat we zien in het embedded wozObject. Is dat wat gewenst is?
@MelvLee bij de andere API's hebben we in een collectie de self-link naar elke resultaat-resource steeds opgebouwd zonder fields of expand query-parameters erin. Is dat correct?
N.B. ik kan het zelf niet halen uit draft-kelly-json-hal en de daarin verwezen rfc5988
@MelvLee bij de andere API's hebben we in een collectie de self-link naar elke resultaat-resource steeds opgebouwd zonder fields of expand query-parameters erin. Is dat correct?
N.B. ik kan het zelf niet halen uit draft-kelly-json-hal en de daarin verwezen rfc5988
Wat ik er uit opmaak is dat de self-link de verwijzing is naar de resource. Het feit dat er voor het tonen van deze resource filtering in de initiele aanroep is toegepast met Fields zou daarop niet van invloed moeten zijn.
Als wij willen dat de self-link exat dezelfde response-body toont als de initiële aanroep (en dat lijkt mij wenselijk voor de discoverability) dan is het goed om hier in ieder geval voor de HC_API's afrspraken over te maken en deze afspraak voor te leggen aan de landelijke REST-API strategie werkgroep die zich met Hypermedia bezighoudt. (Hiervoor is een voorstel gedaan om opgenomen te worden.
Volgens rfc5988 wordt met self het volgende bedoeld:
o Relation Name: self
o Description: Conveys an identifier for the link's context.
o Reference: [RFC4287]
Wat ik mij afvraag wat wordt bedoeld met de context. Als de context is 'de gefilterde resource', dan moet de query parameters waarmee de resource is opgemaakt worden opgenomen. Als wordt geïnterpreteerd de identifier van de resource, dan niet. Volgens mij is het laatste niet het geval
Melvin en ik interpreteren deze rfc verschillend. Ik kan er heel goed mee leven als we Melvins interpretatie gaan gebruiken, maar het lijkt mij wel een goed idee dat dan te documenteren als feature. Lijkt mij er 1 voor de common zodat alle HC-API's zich vergelijkbaar gedragen.
daar is al een feature voor: https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/master/features/self-links.feature
alleen staat daar nu in beschreven dat fields niet in de self link moet zijn opgenomen bij een resource in een collectie.
we kunnen dat niet zomaar aanpassen in common, want BAG en BRK (en in Den Haag ook BRP) werken nu volgens de huidige beschrijving in de feature
daar is al een feature voor: https://github.com/VNG-Realisatie/Haal-Centraal-common/blob/master/features/self-links.feature
alleen staat daar nu in beschreven dat fields niet in de self link moet zijn opgenomen bij een resource in een collectie.
Ik denk dat wij destijds de JSON HAL specificatie niet goed geïnterpreteerd hebben. In de paragraaf Hypertext Cache Pattern interpreteer ik dat deze pattern kan worden toegepast om het clients mogelijk te maken om niet alleen de response bij de initiele request te cachen, maar ook een individuele embedded resource in de response te cachen met de self link behorende bij die resource. Als de initiele request de fields parameter bevat, dan moet aan de self link van elke embedded resource dezelfde fields query parameter worden toegevoegd.
Als mijn interpretatie klopt, dan is de opmerking van Stijn: Wanneer de self link vervolgens geen fields parameter bevat, levert deze link niet het zelfde object dat we zien in het embedded wozObject dus terecht.
we kunnen dat niet zomaar aanpassen in common, want BAG en BRK (en in Den Haag ook BRP) werken nu volgens de huidige beschrijving in de feature
Ik zou het ook niet in de common aanpassen, maar wel op de TODO lijst zetten voor de 2.0 versie.
Ok, goed voorstel. Laten we hier concreet afspraken over maken in het volgende werkoverleg.
Aangezien over dit punt nog onenigheid bestaad, heb ik hem voor nu even gelabeled als invalid, dit is ook handig voor mijn overzicht. Als ik hier mijn edit rights overschreid hoor ik het graag, dan zet ik hem weer terug :)