Starten met ZIBs en FHIR

We gaan ervan uit dat je een Ons API-integratie hebt, minstens op het development stadium. We zullen linken naar de relevante delen van de FHIR specificatie indien van toepassing.

Overzicht van beschikbare endpoints

We leveren verschillende FHIR-eindpunten die altijd ZIB-profielen zullen retourneren. Voor alle beschikbare profielen, zie simplifier. Voor de ondersteunde profielen/ZIBs, zie de ZIB pagina. Deze endpoints zijn beschikbaar in het Ons API Dashboard, allemaal beginnend met /t/fhir, gevolgd door de resource. Er zijn twee endpoints beschikbaar per resource: een read endpoint (zoals /t/fhir/Patient/{id}) en een search endpoint (/t/fhir/Patient).

Lees-endpoints (read)

De lees-endpoints staan alleen toe om een enkele resource te verzamelen op basis van zijn id. Deze id’s bestaan vaak uit een soort uuid. Dit betekent meestal dat ze niet het initiële toegangspunt zijn, maar eerder gebruikt moeten worden om aanvullende verwijzingen te verzamelen na het zoeken naar een bron. Een voorbeeld call kan zijn:

https://api-development.ons.io/t/fhir/Patient/Client.500f9b5e-9248-4c0b-b96d-3bb75d3148ce

Zoek-endpoints (search)

De zoek-endpoints zullen altijd een bundel retourneren, die een lijst bevat van alle resources die zijn gevonden via de search operation. De zoekparameters worden doorgegeven als queryparameters. Verschillende van deze parameters zijn beschikbaar voor elke resource, en om een volledig overzicht te krijgen van beschikbare queryparameters per resource, kun je de capability statement opvragen: /t/fhir/metadata.

Query parameters

Enkele algemene queryparameters zijn beschikbaar in (bijna) alle resources:

• _id is een alias voor het lees-endpoint. Het staat wel het gebruik toe van sommige andere mogelijkheden van het zoek-endpoint, dus er zijn zeker gebruiksscenario’s waarin deze parameter relevant is.
• identifier maakt zoeken mogelijk op basis van een identifier van de resource. Dit is een tokenparameter, wat betekent dat deze is opgebouwd uit twee delen, gescheiden door een verticale streep (|). Het eerste deel is het systeem dat het type van deze identificator definieert (bijv., burgerservicenummer). Het tweede deel is de werkelijke waarde of code.

Als voorbeeld kan een patiënt ZIB worden verzameld op basis van hun burgerservicenummer:

https://api-development.ons.io/t/fhir/Patient?identifier=http://fhir.nl/fhir/NamingSystem/bsn|077461848

Hierbij is http://fhir.nl/fhir/NamingSystem/bsn het syteem en 077461848 de waarde. Voor meer informatie over systemen en codes, zie de informatie die later in dit artikel wordt beschreven.

• subject, patient en subscriber zijn voorbeelden van parameters die filteren op references, meestal een patiënt. We ondersteunen filteren op basis van de id van de reference of op een van de ondersteunde identifier. Deze parameter is in de meeste gevallen het primaire toegangspunt bij het verzamelen van ZIBs rond een specifieke patiënt.

  Het kan op twee manieren worden aangeroepen. We zullen beide voorbeelden geven in de context van Observation resources. Het eerste voorbeeld verzamelt alle observaties voor een specifieke patiënt, op basis van de id van die patiënt:

  https://api-development.ons.io/t/fhir/Observation?subject=Patient/Client.500f9b5e-9248-4c0b-b96d-3bb75d3148ce

  Een andere mogelijkheid is om alle observaties te verzamelen op basis van het burgerservicenummer van de patiënt:

  https://api-development.ons.io/t/fhir/Observation?patient.identifier=http://fhir.nl/fhir/NamingSystem/bsn|432047669

• code is vergelijkbaar met identifier omdat het bestaat uit een combinatie van systeem en waarde. Echter, code verzamelt alle resources die binnen een bepaalde categorie vallen. Een voorbeeld waarbij de woonsituatie van een specifieke patiënt wordt verzameld op basis van zijn burgerservicenummer:

  https://api-development.ons.io/t/fhir/Observation?code=http://snomed.info/sct|365470003&patient.identifier=http://fhir.nl/fhir/NamingSystem/bsn|432047669

• _include staat toe om een gerefereerde resource direct te ontsluiten (include) in de geretourneerde bundel. Normaal gesproken wordt een gerefereerde resource alleen toegevoegd als een id. Als voorbeeld zal deze call alle verzekeringen van een patiënt met een bepaald burgerservicenummer retourneren, en ook die patiënt zelf opnemen in de geretourneerde bundel:

  https://api-development.ons.io/t/fhir/Coverage?subscriber.identifier=http://fhir.nl/fhir/NamingSystem/bsn|556673682&_include=Coverage:payor:Patient

In sommige gevallen moet de verticale streep (|) geëscapet worden door middel van %7C.

ondersteunde identifiers

We ondersteunen het zoeken gebaseerd op identifiers voor organisaties, patiënten en medewerkers/praktijken (practitioners).

Systemen en codes

De systemen die worden gebruikt in codes en categorieën zijn altijd ofwel een snomed code, of lokaal (verwijzend naar interne categorieën). De laatste is alleen beschikbaar voor observaties. Snomed codes kunnen worden opgebouwd als http://snomed.info/sct|365470003 of urn:oid:2.16.840.1.113883.6.96|365470003, waarbij in dit geval 365470003 verwijst naar de woonsituatie van de patiënt.

In het geval van observaties is het ook mogelijk om te zoeken op basis van het reportTypeId van de rapportages, zoals ze beschikbaar zijn via onze traditionele API-endpoints. Een lijst van beschikbare rapporttypen kan worden gevonden door /t/dossier/report_types aan te roepen.

Last-n

Eén speciaal endpoint is beschikbaar voor de Observation resource: $lastn. Dit endpoint zal het laatste nummer van observaties van elk type gerelateerd aan een bepaalde patiënt retourneren. Als er geen n wordt opgegeven via de max query parameter, wordt alleen de meest recente observatie van elk type geretourneerd. Voorbeeld:

https://api-development.ons.io/t/fhir/Observation/$lastn?max=2&subject=Client.500f9b5e-9248-4c0b-b96d-3bb75d3148ce

Als een code wordt opgegeven, worden alleen de laatste n van dat specifieke type observatie geretourneerd:

https://api-development.ons.io/t/fhir/Observation/$lastn?max=3&subject=Client.500f9b5e-9248-4c0b-b96d-3bb75d3148ce&code=http://nedap.com/fhir/NamingSystem/local|report