Hoe omgaan met automatisch laden (embedden) van een relatieklasse about kp-apis HOT 9 CLOSED

Bijvoorbeeld, levert ?expand=partnerschappen in de embedde relatie "partnerschappen" ook een element _embedded met daarin de partner-attributen?

"_embedded": {
    "partnerschappen": [
      {
        "_links": {
          "partners": {
            "href": "http://rvig.nl/api/brp/v1/ingeschrevenpersonen/999999023"
          }
        }, 
        "_embedded": {
          "partners": {
            "_links": {
              "self": {
                "href": "http://rvig.nl/api/brp/v1/ingeschrevenpersonen/555555914"
              }
            }, 
            "burgerservicenummer": "555555914", 
            "geslachtsaanduiding": "C", 
            "naam": {
              "geslachtsnaam": "Groenen", 
              "voornamen": "Anne-Fleur"
            }, 
            "verblijfplaats": {
              "adresherkomst": "W", 
              "huisletter": null, 
              "huisnummer": "23", 
              "huisnummertoevoeging": "2", 
              "identificatiecodeNummeraanduiding": "0518200000366054", 
              "naamOpenbareRuimte": "Loosduinsekade", 
              "postcode": "2571CC", 
              "woonplaatsnaam": "Utrecht"
            }
          }
        }, 
        "aangaanPartnerschap": {
          "datumHuwelijkssluiting_aangaanGeregistreerdPartnerschap": "1989-05-23", 
          "landHuwelijkssluiting_aangaanGeregistreerdPartnerschap": {
            "landcode": "6030", 
            "landnaam": "Nederland"
          }, 
          "plaatsHuwelijkssluiting_aangaanGeregistreerdPartnerschap": "Maarssen"
        }, 
        "ontbindingPartnerschap": null, 
        "soortVerbintenis": "H"
      }

from kp-apis.

Of moet dat specifiek worden bevraagd? Zo ja, hoe? Bijvoorbeeld met expand=partnerschappen._embedded.partners, expand=partnerschappen.partners, expand=partners, o.i.d.?

from kp-apis.

Ik had de werking van de 'expand' eerlijk gezegd anders begrepen ...

Resource van een 'Ingeschreven Persoon' (noem deze voor het gemak even de Persoonslijst) bestaat uit Persoonsgegevens en z'n relaties/gerelateerden (bv. Ouder, Partner, Kind, Nationaliteit, Adres, Reisdocument).

De gegevens van genoemde relaties/gerelateerden zijn standaard onderdeel van de resource (persoonslijst IngeschrevenPersoon) die wordt bevraagd. Welke gegevens van deze resources wel/niet worden geleverd wordt bepaald door het autorisatiemechanisme en de opgave in de 'fields'-parameter. Dus als je in jouw voorbeeld de naam van de partner mee verstrekt wilt krijgen geef je dit in de 'fields'-parameter op.

Als je van een gerelateerde (bv. Ouder, Kind, Partner) in dezelfde bevraging ook de gehele resource (Persoonslijst) wil binnen hengelen, dan kun je de expand gebruiken. Dan ontvang je in het antwoord naast de resource van de IngeschrevenPersoon die je hebt opgevraagd ook de gehele resource van betreffende Ouder(s), Kind(eren) en Partner(s) ... mits deze ook als IngeschrevenPersoon voorkomen.

Voor de ge-'expande' resources gelden dan dezelfde autorisatieregels en 'fields'-beperkingen.

NB. Overigens ben ik geen voorstander van de 'expand' in de eerste versie van de API; zie mijn issue 'To expand or not to expand'. Het heeft mijn voorkeur dat een serviceconsumer op basis van de ontvangen resource vooralsnog een nieuwe bevraging doet voor de gerelateerde persoon waarin hij is geïnteresseerd.

from kp-apis.

Of moet dat specifiek worden bevraagd? Zo ja, hoe? Bijvoorbeeld met expand=partnerschappen._embedded.partners, expand=partnerschappen.partners, expand=partners, o.i.d.?

Ja, dat moet naar mijn mening specifiek bevraagd worden. Van de genoemde opties lijkt expand=partnerschappen.partners het meest logisch. Immers een expand is het omzetten van een link naar een resource in een embedded object. In dit geval gaat het om een geneste oftewel dubbele expand. Eerst wordt de link naar de resource partnerschappen omgezet in een embedded partnerschappen-object en tegelijk daarna wordt binnen dit partnerschappen-object de relatie naar partners omgezet naar een embedded partners-object.

In deze interepretatie heeft expand betrekking op het expanden van links en niet van elementen. Dus de optie expand=partnerschappen._embedded.partners is naar mijn mening niet juist. De optie expand=partners zou een shortcut kunnen zijn voor expand=partnerschappen.partners omdat de API af zou kunnen leiden dat de link naar de resource partners een geneste relaties is binnen partnerschappen. Voor nu lijkt me een dergelijke verkorte notatie iets te ambitieus.

from kp-apis.

Ben het trouwens wel eens met @gertjanvanderkooij dat de expand en fields parameters mogelijk overlap kunnen hebben qua functionaliteit en dat de semantiek van beide query parameters heel goed gespecificeerd moeten worden zodat ze niet met elkaar conflicteren.

from kp-apis.

Ja, dat moet naar mijn mening specifiek bevraagd worden. Van de genoemde opties lijkt expand=partnerschappen.partners het meest logisch

Deze snap ik vanuit techniek geredeneerd, niet vanuit functionele behoefte. Ik denk dat bijna altijd wanneer je het partnerschap (bijv. ingangsdatum) wil weten, dan ook gelijk de gegevens van de partner wilt.

De gegevens van genoemde relaties/gerelateerden zijn standaard onderdeel van de resource (persoonslijst IngeschrevenPersoon) die wordt bevraagd.

Dit is op zich een mooie oplossing, maar dan lopen we wel tegen een probleem aan met JSON HAL. Wanneer de eigenschappen van de relatie in de resource zitten, maar de link naar de gerelateerde in _links, is de relatie tussen beide niet meer duidelijk. Hoe lossen we dat op?

Bijvoorbeeld in dit voorbeeld kan je niet zien welke ouder ouder1 is en welke ouder ouder2:

{
  "_links": {
    "ouders": [
      {
        "href": "http://voorbeeld.nl/api/v1/ingeschrevenpersonen/999999047"
      }, 
      {
        "href": "http://voorbeeld.nl/api/v1/ingeschrevenpersonen/999999051"
      }
    ], 
    "self": {
      "href": "http://voorbeeld.nl/api/v1/ingeschrevenpersonen/999999023"
    }
  },
  "ouderschappen": [
    {
      "ouder_aanduiding": "1"
    }, 
    {
     "ouder_aanduiding": "2"
    }
  ]
}

from kp-apis.

Ik denk dat bijna altijd wanneer je het partnerschap (bijv. ingangsdatum) wil weten, dan ook gelijk de gegevens van de partner wilt.

Als dat zo is dan is het een logische designkeuze om deze dus ook altijd mee te geven en geen expand te hoeven gebruiken.

Bijvoorbeeld in dit voorbeeld kan je niet zien welke ouder ouder1 is en welke ouder ouder2

Is dat belangrijk? Zo ja, dan zegt ouder 1 mij nog niks, ik neem aan dat het dan de usecase is om te zien of iemand vader of moeder is? Want dan krijg je m.i. gewoon:

{
  "_links": {
    "vader": {
        "href": "http://voorbeeld.nl/api/v1/ingeschrevenpersonen/999999047"
      },
      "moeder": {
        "href": "http://voorbeeld.nl/api/v1/ingeschrevenpersonen/999999047"
      }
  }
}

from kp-apis.

Voorstel werkgroep: laatste twee onderdelen paragraaf 4.2.4 verwijderen en paragraaf 4.2.5 volledig verwijderen. Daarnaast API-principe 08 verwijderen.

from kp-apis.

Voorstel werkgroep verwerkt.

from kp-apis.