Skip to main content Link Menu Expand (external link) Copy Copied
Ons API

Dataminimalisatie / filtering

Veel soorten data die we namens zorgorganisaties verwerken zijn aangemerkt als gevoelige informatie. Zoals aangegeven in het artikel Ontwikkelstadia en beoordelingscriteria is een van onze vereisten voor het goedkeuren van een connector dat alleen benodigde en doelmatige informatie via Ons API uitgewisseld wordt. We faciliteren in het minimaliseren van data door filtermogelijkheden op drie niveau’s aan te bieden, welke hieronder staan toegelicht.

Soorten filtering

Filtering op basis van API’s

Tijdens het development-stadium zijn alle API’s beschikbaar (filtering van endpoints is tijdens dit stadium in- en uit te schakelen). Voordat toegang naar de volgende stadia wordt toegestaan, dient gespecificeerd te zijn welke API’s benodigd zijn. Dit doen we om verzekerd te zijn dat een connector geen toegang heeft tot meer informatie dan nodig is. De lijst van de voor de connector beschikbare API’s is voor zorgorganisaties inzichtelijk, waardoor deze weet welke soort informatie uitgewisseld kan worden met welke connector.

Filtering van velden per model

Elk model heeft een set met velden. We vereisen dat de meest beperkte hoeveelheid velden geselecteerd wordt in relatie tot het doel en functioneel ontwerp van de connector. Bijvoorbeeld: de connector heeft diverse medewerkergegevens ‘employee’ nodig, maar geen telefoonnummer. In dat geval dient het telefoonnummer niet geselecteerd te zijn. Deze filtering is van toepassing op GET-endpoints. Voor elke GET-request waarvan het veld niet geselecteerd is, zullen de resultaten eruit worden gefilterd. Voor PUT- of POST-requests geldt dit niet, aangezien het bronsysteem niet Nedap is. Deze gegevens zijn daarom altijd, ongeacht of deze geselecteerd zijn, van een extern systeem naar Nedap te versturen.

De lijst met de voor de connector beschikbare velden is, net zoals die van de API’s, inzichtelijk voor zorgorganisaties.

Filtering van velden per request

Het is mogelijk om het ophalen van informatie van bepaalde velden verder te limiteren. Dit is te doen op een per-request basis. Het kan handig zijn als er gedetailleerde resultaten voor bepaalde velden nodig zijn, maar er eerst geïnventariseerd moet worden op welke dit van toepassing is. Het is mogelijk om dit te doen met een header X-Field-Whitelist en comma-separated list met velden die gefilterd worden voor het betreffende request. De respons bevat een set met velden op het kruisvlak van de set die is gespecificeerd in de header en de set die gespecificeerd is in de configuratie (limitering van velden per model).

  • De namen van de gespecificeerde velden in deze header zijn case sensitive.
  • Deze functionaliteit werkt alleen als filtering voor endpoints is ingeschakeld.
  • Welke informatie op deze manier gefilterd wordt is niet voor zorgorganisaties te zien.

Kanttekeningen

GET-filtering per veld in combinatie met latere PUT-requests

Filtering van velden per model is alleen van toepassing op GET-endpoints, maar niet op POST en PUT endpoints. In het geval er binnen hetzelfde model eerst met GET op velden wordt gefilterd, en vervolgens PUT of POST requests worden gedaan, dan bestaat het risico dat data verwijderd wordt. Dit komt omdat:

  • De connector alleen toegang heeft tot een subset van de velden (gespecificeerd in het model), en;
    • De connector niet de waarde van de niet-toegankelijk velden kan specificeren bij een PUT of POST request, omdat deze niet bekend zijn;
      • En daarom zullen deze gewist worden.

Conclusie: Als je op velden in een model POST of PUT requests wil doen, zorg dan dat alle velden in een model toegankelijk zijn.

Zie ook het voorbeeld dat later in dit artikel beschikbaar is.

Filtering van velden ondersteunt geen geneste modellen

Soms bevatten modellen andere modellen. Een voorbeeld is het Client model:

{
	"id": 1,
	"firstName": "Mike",
	...
	"careAllocations": [
		{
		"id": 1,
		"clientId": 10,
		"beginDate": "2016-01-01",
		"endDate": "2020-01-01",
		"comments": "niets te melden",
		"destination": "EIGEN_OMGEVING",
		"reason": "IN_CARE",
		"reasonTemporary": "VAKANTIEVERLOF"
		}
	],
	...
}

In dergelijke gevallen zal filtering op velden ofwel de volledige inhoud tonen van careAllocations (indien dit veld is geselecteerd), of het volledige veld weglaten. Er is geen mogelijkheid om de velden binnen careAllocations te filteren.

Voorbeelden

Verwijdering van data bij een PUT-request in combinatie met GET-filtering
Stel het volgende record voor, uit een denkbeeldig Domain model:

{
  "id": 1,
  "topLevelDomain": "nl",
  "domain": "ons-api",
  "subDomain": "www"
}

Stel je een connector voor welke toegang heeft tot zowel GET en PUT op /t/domains/{id}, en die toegang heeft tot de velden id, topLevelDomain en domain, (maar niet subDomain) van hetDomain model.

Een eenvoudige GET request haalt de te verwachten velden op:

GET /t/domains/1 HTTP/2
Host: api-development.ons.io
Accept: application/json

{
  "id": 1,
  "topLevelDomain": "nl",
  "domain": "ons-api"
}

Maar nu gaan we dezelfde data invoeren met een request op het PUT endpoint:

PUT /t/domains/1 HTTP/2
Host: api-development.ons.io
Content-Type: application/json
Content-Length: 42

{
  "id": 1,
  "topLevelDomain": "nl",
  "domain": "ons-api"
}

Dit zal resulteren in gewijzigde data op onze server, en wel als volgt:

{
  "id": 1,
  "topLevelDomain": "nl",
  "domain": "ons-api",
  "subDomain": null
}

Merk op dat het veld waar de connector geen toegang toe had hiermee is gewijzigd naar ‘null’ omdat deze niet werd meegegeven in de PUT-request.

Verschillende manieren van het filteren per veld
Stel het volgende record voor, uit een denkbeeldig Domain model:

{
  "id": 10,
  "topLevelDomain": "nl",
  "domain": "ons-api",
  "subDomain": "www"
}

Neem aan dat een connector toegang heeft tot zowel GET /t/domains/{id} als tot de velden id,topLevelDomain en domain (maar niet subDomain) op het Domain model.

Een eenvoudige GET request haalt de te verwachten velden op:

GET /t/domains/1 HTTP/2
Host: api-development.ons.io
Accept: application/json

{
  "id": 1,
  "topLevelDomain": "nl",
  "domain": "ons-api"
}

Het ophalen van minder velden dan de ‘default’ is mogelijk door dit te specificeren met de X-Field-Whitelist header:

GET /t/domains/1 HTTP/2
Host: api-development.ons.io
Accept: application/json
X-Field-Whitelist: id, topLevelDomain

{
  "id": 1,
  "topLevelDomain": "nl"
}

Met gebruik van de X-Field-Whitelist header is het niet mogelijk om meer velden aan te roepen dan waartoe toegang is verleend. De respons zal alle velden bevatten die in de header zijn gespecificeerd en waartoe ook in de configuratie toegang toe is verleend. Voorbeeld:

GET /t/domains/1 HTTP/2
Host: api-development.ons.io
Accept: application/json
X-Field-Whitelist: topLevelDomain, domain, subDomain

{
  "topLevelDomain": "nl",
  "domain": "ons-api"
}

Merk op dat het veld id niet opgevraagd is en daarom ook niet teruggegeven. Het veld subDomain is opgevraagd, maar ook niet teruggegeven, omdat hiertoe in de configuratie geen toegang toe is verleend.