Oplossingsrichting #953

[kad-hebbim]

Probleem

Opvragen persoon of de kadastraalOnroerendeZaken bij een persoon waarbij er nu een timeout optreedt op de zakelijkgerechtigden.

Oplossing

Het mogelijk maken om een persoon op te vragen zonder de zakelijkgerechtigden erbij, door:

• zakelijkgerechtigden uit te sluiten via de fields parameter óf
• alleen de zakelijkgerechtigden als collectie op te vragen (ook middels de fields parameter)

WAS:

Opvragen persoon

1. /kadasternietnatuurlijkpersonen/1
   1. timeout

    {
     "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1",
     "title": "Interne server fout.",
     "status": 500,
     "detail": "The server encountered an unexpected condition which prevented it from fulfilling the request.",
     "instance": "/kadasternietnatuurlijkpersonen/1",
     "code": "serverError"
    }
   

WORDT:

Opvragen persoon

1. /kadasternietnatuurlijkpersonen/1
   1. melding dat resource niet op te vragen is inclusief zakelijkgerechtigden.

    {
        "type": "https://docs.microsoft.com/en-us/dotnet/api/system.net.httpstatuscode?#SystemNetHttpStatusCodeBadRequest",
        "title": "Object kan niet opgevraagd worden inclusief de zakelijkgerechtigden.",
        "status": 400,
        "detail": "Opgevraagde resource kan niet opgevraagd worden inclusief de zakelijkgerechtigden. Gebruik een fields parameter om de zakelijkgerechtigden uit te sluiten of gebruik zakelijkGerechtigdenCollectie om alleen de collectie terug te geven.
        "instance": "/kadasternietnatuurlijkpersonen/1",
        "code": "notRequestable"
    }
   

Opvragen persoon met zakelijkgerechtigden als collectie

3. /kadasternietnatuurlijkpersonen/1?fields=omschrijving,woonadres,kadastraalOnroerendeZaakIdentificaties,statutaireNaam,statutaireZetel,rechtsvorm,links.kadastraalOnroerendeZaken,zakelijkGerechtigdenCollectie

   {
       "identificatie": "1",
       "omschrijving": "Bedrijf x",
       "domein": "NL.IMKAD.Persoon",
       "woonadres": {
           "straat": "Straat",
           "huisnummer": 1,
           "postcode": "1111AA",
           "woonplaats": "Apeldoorn"
       },
       "kadastraalOnroerendeZaakIdentificaties": [
           "76870482570000",
           "76870488070000"
       ],
       "statutaireNaam": "Bedrijf x",
       "statutaireZetel": "APELDOORN",
       "rechtsvorm": {
           "code": "2",
           "waarde": "Besloten vennootschap"
       },
       "_links": {
           "self": {
               "href": "/kadasternietnatuurlijkpersonen/1?fields=omschrijving,woonadres,kadastraalOnroerendeZaakIdentificaties,statutaireNaam,statutaireZetel,rechtsvorm,links.kadastraalOnroerendeZaken"
           },
           "kadastraalOnroerendeZaken": [
               {
                   "href": "/kadastraalonroerendezaken/{kadastraalOnroerendeZaakIdentificaties}",
                   "templated": true
               }
           ],
           "zakelijkGerechtigdenCollectie": {
               "href": "/kadastraalonroerendezaken/{kadastraalOnroerendeZaakIdentificaties}/zakelijkgerechtigden",
               "templated": true
           }
       }
   }
   

Opvragen persoon zonder zakelijkgerechtigden

2. /kadasternietnatuurlijkpersonen/1?fields=omschrijving,woonadres,kadastraalOnroerendeZaakIdentificaties,statutaireNaam,statutaireZetel,rechtsvorm,links.kadastraalOnroerendeZaken

    {
        "identificatie": "1",
        "omschrijving": "Bedrijf x",
        "domein": "NL.IMKAD.Persoon",
        "woonadres": {
            "straat": "Straat",
            "huisnummer": 1,
            "postcode": "1111AA",
            "woonplaats": "Apeldoorn"
        },
        "kadastraalOnroerendeZaakIdentificaties": [
            "76870482570000",
            "76870488070000"
        ],
        "statutaireNaam": "Bedrijf x",
        "statutaireZetel": "APELDOORN",
        "rechtsvorm": {
            "code": "2",
            "waarde": "Besloten vennootschap"
        },
        "_links": {
            "self": {
                "href": "/kadasternietnatuurlijkpersonen/1?fields=omschrijving,woonadres,kadastraalOnroerendeZaakIdentificaties,statutaireNaam,statutaireZetel,rechtsvorm,links.kadastraalOnroerendeZaken"
            },
            "kadastraalOnroerendeZaken": [
                {
                    "href": "/kadastraalonroerendezaken/{kadastraalOnroerendeZaakIdentificaties}",
                    "templated": true
                }
            ]
        }
    }
   

• Bovenstaande geldt voor de volgende endpoints:
  • /kadasternietnatuurlijkpersonen/{identificatie}
  • /kadasternietnatuurlijkpersonen?q={zoekterm}
  • /kadasternatuurlijkpersonen/{identificatie}
  • /kadasternatuurlijkpersonen?q={zoekterm}
  • /kadastraalonroerendezaken?persoon__identificatie={identificatie}
  • /kadastraalonroerendezaken?burgerservicenummer={bsn}

Kanttekening

• fields parameter kan lang worden als je alleen zakelijkgerechtigden wilt uitsluiten.
• bij geen gebruik van fields krijg je zowel links.zakelijkGerechtigden als links.zakelijkGerechtigdenCollectie terug.

[CathyDingemanse]

Ziet er goed uit, zoals besproken. Kunnen jullie e.e.a. ook aan de specificaties toevoegen, zodat gebruikers zich hierop kunnen voorbereiden?

[kad-hebbim]

Aangezien het nu wel een aardig omslachtige manier van werken is geworden wil ik toch nog een ander voorstel doen.

Ik vraag me namelijk af hoe deze endpoints nu precies gebruikt worden door de afnemers. Worden de links naar de zakelijkGerechtigden hier überhaupt wel gebruikt?

Kan me namelijk goed voorstellen dat ze toch altijd nog een aparte bevraging doen naar elke onroerendeZaak die ze terugkrijgen voor de persoon die ze bevragen om meer informatie over deze onroerendeZaak te krijgen. Daar krijgen ze dan ook al deze zakelijkGerechtigden terug. Dan zou de route dus worden (een tweetraps raket):

• Opvragen persoon, welke een lijst met onroerendeZaakIdentificaties teruggeeft:
  /kadasternietnatuurlijkpersonen/1

• Per onroerendeZaak (of de onroerendeZaak die ze willen bevragen) de gegevens ophalen:

  • /kadastraalonroerendezaken/2
    Per zakelijkGerechtigde (of de zakelijkGerechtigde die ze willen bevragen) de gegevens ophalen
    /kadastraalonroerendezaken/2/zakelijkgerechtigden/3

  of direct

  • /kadastraalonroerendezaken/2?expand=zakelijkgerechtigden

Aangezien het pijnpunt zit in het tonen van de links naar de individuele zakelijkgerechtigdeIdentificaties in deze resource, zouden we deze geheel kunnen verwijderen in de resource (is waarschijnlijk wel een breaking-change, maar wordt het nu al veel gebruikt door de afnemers??) waardoor:

• deze endpoints op een eenduidige manier werken, immers je krijgt altijd dezelfde resultaat terug; gegevens van de persoon plus een lijst met onroerendeZaken. Ongeacht hoeveel objecten de persoon op naam heeft.
• de afnemers niet met fields hoeven gaan werken om de zakelijkgerechtigden te filteren; aangezien ze anders geen gegevens van de persoon kunnen terugkrijgen.

[PeaceNlove]

Afnemer hierzo:

Wat ik wil is als volgt:
-ik heb geografisch een perceel gevonden op de kaart, van dat perceel wil ik de gegevens van de zakelijk gerechtigden weten, inclusief adresgegevens
-ik bevraag /kadastraalonroerendezaken/ met het perceelnummer, en een expand op de zakelijkgerechtigden
-vervolgens bevraag ik in het geval van een kadaster_natuurlijk_persoon of kadaster_niet_natuurlijk_persoon de endpoints kadasternietnatuurlijkpersonen of kadasternatuurlijkpersonen, waarbij ik dan alleen geïnteresseerd ben in de adresgegevens van die persoon.

Voor zover ik kon zien krijg ik die adresgegevens bij de expand op zakelijkgerechtigden er niet bij, dus vandaar de 2e api call om die adresgegevens er bij te bevragen.

[kad-hebbim]

Zie issue #962