Doel en gebruik van de COR API.md

Doel en gebruik van de COR API

De Centrale OIN Raadpleegvoorziening is te bevragen via een REST API. Met de API kunnen de OIN’s van geregistreerde organisaties worden opgevraagd en de organisatienamen bij bestaande OIN’s worden opgezocht.

De COR API biedt de volgende services aan:

  • Opvragen OIN en organisatienamen zonder parameters
  • Opvragen OIN en organisaties met parameters
  • Opvragen enkele organisatie
  • Opvragen laatste wijziging op de COR database

Voor het opvragen van organisaties kan gefilterd worden op: OIN, naam, status, organisatie code, organisatie Type en KvK nummer. Deze filters kunnen gecombineerd worden.

De COR API REST services zijn te gebruiken door gebruikers die beschikken over een PKIOverheid certificaat. Vanaf versie 1.1 retourneert de COR API in HAL+JSON formaat.

Organisaties worden getoond met de volgende gegevens:

  1. oin: OIN van de organisatie
  2. naam: Naam van de organisatie
  3. status: Status van de organisatie (Actief of Ingetrokken)
  4. kvkNummer: KvK nummer van de organisatie
  5. organisatieCode: Organisatiecode van een organisatie. Alleen gevuld voor gemeenten (bron https://rvig.nl ), provincies en waterschappen/hoogheemraadschappen (bron https://cbs.nl).
  6. organisatieType – Type van de organisatie. Alleen als organisatie een gemeente (type=GM), provincie (type=PV) of waterschap of hoogheemraadschap is (type=WS)
  7. afgifteDatum – Afgiftedatum van het OIN van de organisatie
  8. laatstAangepastDatum – Laatst datum waarop het OIN van de organisatie is aangepast
  9. intrekdatum – Datum waarop het OIN van de organisatie is ingetrokken.
  10. hoofdOin – Details van de organisatie met het hoofdOIN (wanneer de organisatie een subOIN heeft)
  11. subOINs – Lijst met details van de organisaties met subOINs (wanneer de organisatie een hoofdOIN heeft)

Samen met de bovengenoemde informatie wordt ook de HAL informatie doorgegeven. Deze bestaat uit de onderstaande gegevens:

  1. _links: Dit is de parent tag voor HAL content. Het bevat de onderstaande details.
  2. self: Dit is de informatie over de resource die momenteel wordt benaderd. Het bevat de attributen ‘href’ en ‘type’.
  3. href: Dit bevat de URL waarmee de huidige resource kan worden benaderd. Het kan ook worden gebruikt als een referentie naar de parent tag waaronder deze wordt vermeld (ook wel ‘next’)
  4. type: Dit beschrijft het content type van de opgevraagde resources.

De HAL informatie bevat ook pagineringsinformatie zoals hieronder beschreven:

  1. first: Dit bevat informatie voor het verkrijgen van toegang tot de eerste pagina van de opgehaalde resultaten.
  2. prev: Dit bevat informatie voor het verkrijgen van toegang tot de vorige pagina van de opgehaalde resultaten.
  3. next: Dit bevat informatie voor het verkrijgen van toegang tot de volgende pagina van de opgehaalde resultaten.
  4. last: Dit bevat informatie voor het verkrijgen van toegang tot de laatste pagina van de opgehaalde resultaten.

Alle services maken gebruik van onderstaande statuscodes:

  1. 200: Wanneer een request succesvol is en een response beschikbaar is.
  2. 400: Wanneer een request fout is gegaan of ongeldige parameters zijn meegegeven.
  3. 404: Wanneer er geen resultaten voor een request zijn of een verkeerde URL is ingevoerd:
  4. 405: Wanneer een request niet via de methode GET wordt gedaan.
  5. 406: Wanneer de ‘Accept’ header in het request niet ‘application/json’ is terwijl dit wel : dt gevraagd.
  6. 500: Wanneer zich een interne server fout heeft voorgedaan.

Er zijn enkele custom response headers die met een response worden meegestuurd:

  1. X-API-Version: De huidige versie van de COR API die wordt ondervraagd
  2. X-Total-Count: Het totale aantal resultaten van de huidige zoekopdracht
  3. X-Pagination-Count: Het totale aantal pagina’s voor de huidige zoekopdracht
  4. X-Pagination-Page: De huidige pagina die opgevraagd is voor de zoekopdracht
  5. X-Pagination-Limit: Het maximale limiet van 30 per pagina zoals dat is bepaald door de applicatie.

Er zijn twee request headers die naar de server moeten worden gestuurd:

  1. Accept: Deze header specificeert het gewenste format van de response. De applicatie ondersteunt momenteel application/hal+json. Deze header is verplicht.
  2. Accept-Version: Deze header specificeert welke versie van de service de client wil benaderen. Op dit moment biedt de applicatie versie 1.0 en 1.1 aan. 1.1 is de default waarde. Deze header is optioneel.

Standaarden

Service beschrijving

Opvragen organisaties zonder parameters

Omschrijving Deze service geeft de gegevens van alle organisaties terug met de status “actief” of “ingetrokken”.
URL https://portaal.digikoppeling.nl/registers/api/v<x>/organisaties
HTTP method GET
Headers Accept = application/hal+json
Voorbeeld request(s) https://portaal.digikoppeling.nl/registers/api/v1/organisaties

Opvragen organisaties met parameters

Omschrijving Deze service retourneert de gegevens van de organisaties op basis van de query in de request
URL https://portaal.digikoppeling.nl/registers/api/v<x>/organisaties? <params>
HTTP method GET
Headers Accept = application/hal+json
Voorbeeld request(s)
één filter https://portaal.digikoppeling.nl/registers/api/v1/organisaties?oin=12345678901234567890
meerdere filters https://portaal.digikoppeling.nl/registers/api/v1/organisaties?organisationCode=1234&organisationType=GM
De bovengenoemde filters worden toegepast met daarbij een ‘AND’ conditie wanneer meerdere filters worden gebruikt

Parameters organisaties met parameters

Beschrijving Parameter Details
OIN nummer oin OIN nummer is 20 cijfers lang. Het betreft hier een ‘equals’ conditie, dus moet het complete OIN nummer van de organisatie worden meegegeven om een resultaat te krijgen
Organisatienaam naam Het betreft hier een ‘equals’ conditie, dus moet de complete organisatienaam van de organisatie worden meegegeven om een resultaat te krijgen.
Status van het OIN status Geaccepteerde waardes zijn ‘Actief’ en ‘Ingetrokken’
Organisatiecode organisatieCode De organisatiecode moet 4 karakters lang zijn. Het betreft hier een ‘equals’ conditie, dus moet de complete organisatiecode van de organisatie worden meegegeven om een resultaat te krijgen<sup>1</sup>.
Organisatie Type organisatieType Het organisatietype moet 2 karakters lang zijn. Het betreft hier een ‘equals’ conditie, dus moet het complete organisatietype van de organisatie worden meegegeven om een resultaat te krijgen<sup>1</sup>.
KVK-nummer van de organisatie kvkNummer KVKnummer van de organisatie moet 8 cijfers lang zijn. Het betreft hier een ‘equals’ conditie, dus moet het complete KVK-nummer van de organisatie worden meegegeven om een resultaat te krijgen.
Vrije-tekst zoeken zoek Er wordt gezocht op een match met organisatienaam, OIN of afkorting. Het betreft hier een ‘like’ conditie. Hier kunnen deze ook delen van nummers en woorden worden ingevoerd om zoekresultaten terug te krijgen
“lazy” en “eager” laden van relaties expand Deze parameter kan worden gebruikt om alle details van geassocieerde subOins of het hoofdOin van de Organisatie op te vragen. Als de waarde ‘false’ is worden alleen de OIN nummers voor de betreffende organisaties opgehaald. Als de waarde ‘true’ is worden alle details opgehaald. Default: ‘false’.
Paginering pagina Deze parameter wordt gebruikt om de betreffende pagina op te halen. Het maximale aantal resultaten per pagina is ingesteld op 30. De geldige waarden zijn 1 en waarden hoger dan 1.

<sup>1</sup>Alleen gemeentelijke organisaties (GM), provincies (PV) en waterschappen/hoogheemraadschappen (WS) kennen een organisatiecode en -type. Voor de overige organisaties in het OIN register zijn deze waarden niet ingevuld.

Opvragen enkele organisatie

Omschrijving Deze service geeft alle gegevens van een specifieke organisatie terug op basis van de meegegeven OIN
URL https://portaal.digikoppeling.nl/registers/api/v1/organisaties/<oin>
HTTP method GET
Headers Accept = application/HAL+json
Voorbeelden
Gebruik zonder parameter https://portaal.digikoppeling.nl/registers/api/v1/organisaties/12345678901234567890
Gebruik met parameter https://portaal.digikoppeling.nl/registers/api/v1/organisaties/12345678901234567890?expand=true

Parameters enkele organisatie

Beschrijving Parameter Details
“lazy” en “eager” laden van relaties expand Deze parameter kan worden gebruikt om alle details van geassocieerde subOINs of het hoofdOin van de organisatie op te vragen. Als de waarde ‘false’ is worden alleen de OIN nummers voor de betreffende organisaties opgehaald. Als de waarde ‘true’ is worden alle details opgehaald. Default: ‘false’.

Opvragen laatste wijziging op de COR database

Omschrijving Deze service toont de datum-tijd van de laatste wijziging van een gegeven in de database van de COR applicatie. Hiermee kan de gebuiker zien of er sinds de laatste synchronisatieslag nog gegevens zijn gewijzigd in de COR.
URL https://portaal.digikoppeling.nl/registers/api/v1/laatsteWijziging
HTTP method GET
Headers Accept = application/HAL+json
Voorbeeld https://portaal.digikoppeling.nl/registers/api/v1/laatsteWijziging

voorbeelden response berichten

Voorbeeld response bericht bevragen van organisaties

{
  "_links": {
    "self": {
      "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties?pagina=10",
      "type": "application/hal+json"
    },
    "first": {
      "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties?pagina=1",
      "type": "application/hal+json"
    },
    "prev": {
      "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties?pagina=9",
      "type": "application/hal+json"
    },
    "next": {
      "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties?pagina=11",
      "type": "application/hal+json"
    },
    "last": {
      "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties?pagina=31",
      "type": "application/hal+json"
    }
  },
  "organisaties": [
    {
      "_links": {
        "self": {
          "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000001234567891000",
          "type": "application/hal+json"
        }
      },
      "oin": "00000001234567891000",
      "naam": "Gemeente Test",
      "status": "Actief",
      "kvkNummer": "12345678",
      "organisatieCode": "0163",
      "organisatieType": "GM",
      "afgifteDatum": "2009-12-10T23:00:00Z",
      "laatstAangepastDatum": "2016-05-26T22:00:00Z",
      "intrekDatum": null,
      "hoofdOIN": null,
      "subOINs": null
    },
    {
      "_links": {
        "self": {
          "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000001234561259000",
          "type": "application/hal+json"
        }
      },
      "oin": "00000001234561259000",
      "naam": "Gemeente Sluis",
      "status": "Actief",
      "kvkNummer": null,
      "organisatieCode": "1234",
      "organisatieType": "GM",
      "afgifteDatum": "2014-06-04T22:00:00Z",
      "laatstAangepastDatum": "2014-08-25T22:00:00Z",
      "intrekDatum": null,
      "hoofdOIN": null,
      "subOINs": null
    },
    {
      "_links": {
        "self": {
          "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000001001600123456",
          "type": "application/hal+json"
        }
      },
      "oin": "00000001001600123456",
      "naam": "Gemeente Test A",
      "status": "Actief",
      "kvkNummer": null,
      "organisatieCode": "9999",
      "organisatieType": "GM",
      "afgifteDatum": "2010-03-07T23:00:00Z",
      "laatstAangepastDatum": "2014-07-02T22:00:00Z",
      "intrekDatum": null,
      "hoofdOIN": null,
      "subOINs": null
    },
  ]
}

Voorbeeld response bericht voor bevragen van een organisatie met parameter expand=true

{
    "_links": {
        "self": {
            "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000002811223344007?expand=true",
            "type": "application/hal+json"
        }
    },
    "organisaties": [
        {
            "_links": {
                "self": {
                    "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000002811223344007",
                    "type": "application/hal+json"
                }
            },
            "oin": "00000002811223344007",
            "naam": "Midden Test",
            "status": "Actief",
            "kvkNummer": "17155555",
            "organisatieCode": null,
            "organisatieType": null,
            "afgifteDatum": "2014-10-29T23:00:00Z",
            "laatstAangepastDatum": "2014-12-29T23:00:00Z",
            "intrekDatum": null,
            "hoofdOIN": {
                "_links": {
                    "self": {
                        "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000001111111111000",
                        "type": "application/hal+json"
                    }
                },
                "oin": "00000001111111111000",
                "naam": "Noordoost-Test",
                "status": "Actief",
                "kvkNummer": "10000000",
                "organisatieCode": null,
                "organisatieType": null,
                "afgifteDatum": "2014-10-29T23:00:00Z",
                "laatstAangepastDatum": "2014-12-28T23:00:00Z",
                "intrekDatum": null,
                "hoofdOIN": null,
                "subOINs": null
            },
            "subOINs": null
        }
    ]
}

Voorbeeld response bericht voor bevragen van een organisatie met parameter expand=false

{
    "_links": {
        "self": {
            "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000002222222222222",
            "type": "application/hal+json"
        }
    },
    "organisaties": [
        {
            "_links": {
                "self": {
                    "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000002222222222222",
                    "type": "application/hal+json"
                }
            },
            "oin": "00000002811415454007",
            "naam": "Midden Test",
            "status": "Actief",
            "kvkNummer": "17888888",
            "organisatieCode": null,
            "organisatieType": null,
            "afgifteDatum": "2014-10-29T23:00:00Z",
            "laatstAangepastDatum": "2014-12-29T23:00:00Z",
            "intrekDatum": null,
            "hoofdOIN": {
                "_links": {
                    "self": {
                        "href": "https://portaal.digikoppeling.nl/registers/api/v1/organisaties/00000001111111111000",
                        "type": "application/hal+json"
                    }
                }
            },
            "subOINs": null
        }
    ]
}