Hier vindt u alle informatie voor ontwikkelaars
Zorgplatform Resource protocol
Gebruikte standaarden
Request
Response
Foutafhandeling
Zorgplatform Resource protocol
Gebruikte standaarden
Request
Response
Foutafhandeling
Het Zorgplatform ‘Resource protocol’ faciliteert het gebruik van FHIR (Fast Healthcare Interoperability Resources) door een partnerapplicatie. Zorgplatform biedt een FHIR server die wordt gehost op https://api.zorgplatform.online/fhir/{Version}.
Zorgplatform ondersteunt de laatste en de één-na-laatste versie van FHIR. Requests naar dit endpoint vereisen authenticatie in de HTTP-Authorization-header. Autorisatie vindt plaats op basis van toestemming om gegevens uit te wisselen van de patiënt, of workflow in het kader waarvan gegevens uitgewisseld mogen worden. In dit protocol wordt het ophalen (Read/GET), toesturen (Create/POST) en afhandelen (Update/PUT) van resources uitgewerkt.
Gebruikte standaarden
Gebruikte standaarden
HL7 FHIR Om Zorgplatform RESTful APIs aan te roepen, wordt gebruik gemaakt van FHIR interacties (o.a. create, read en update). Zorgplatform ondersteunt de laatste en de één-na-laatste versie van FHIR.
ZIB De informatie in resourcesis conformde zorginformatiebouwstenen (ZIBs).
HTTP-Authorization-header Zorgplatform RESTful APIs maken gebruiken van de HTTP-Authorization-header voor authenticatie en autorisatie.
SAML 2.0 Zorgplatform gebruikt uitsluitend SAML 2.0 assertions als security token.
IHE XUA Zorgplatform SAML 2.0 assertions voldoen aan het IHE XUA integration profile.
HL7 FHIR Om Zorgplatform RESTful APIs aan te roepen, wordt gebruik gemaakt van FHIR interacties (o.a. create, read en update). Zorgplatform ondersteunt de laatste en de één-na-laatste versie van FHIR.
ZIB De informatie in resourcesis conformde zorginformatiebouwstenen (ZIBs).
HTTP-Authorization-header Zorgplatform RESTful APIs maken gebruiken van de HTTP-Authorization-header voor authenticatie en autorisatie.
SAML 2.0 Zorgplatform gebruikt uitsluitend SAML 2.0 assertions als security token.
IHE XUA Zorgplatform SAML 2.0 assertions voldoen aan het IHE XUA integration profile.
Request
Request
HTTP GET application/fhir+json
HTTP POST application/fhir+json
HTTP PUT application/fhir+json
Een partnerapplicatie kan bij de Zorgplatform FHIR server de volgende FHIR interacties uitvoeren: read (GET), create (POST), en update (PUT). Hieronder worden deze interacties uitgewerkt. Het security token (enkel de assertion) verkregen volgens het Service authenticatie protocol wordt meegegeven als Base64encoded string in de HTTP Authorization header. Als schema wordt ‘Saml’ gebruikt:
Authorization: SamlYWxhZGRpbjpvcGVuc2VzYW1l....
Indien er sprake is van een workflow-ID in het token, dient dit overeen te komen met het workflow-ID van de werkstroom in het kader waarvan data uitgewisseld mogen worden. Voor sommige resources en sommige requests moet het ID van de resource worden gebruikt in de URL. Andere resources worden impliciet opgehaald met een zoekopdracht. De base van het endpoint waar resources op te halen zijn, is:
https://api.zorgplatform.online/fhir/{Version}
HTTP GET application/fhir+json
HTTP POST application/fhir+json
HTTP PUT application/fhir+json
Een partnerapplicatie kan bij de Zorgplatform FHIR server de volgende FHIR interacties uitvoeren: read (GET), create (POST), en update (PUT). Hieronder worden deze interacties uitgewerkt. Het security token (enkel de assertion) verkregen volgens het Service authenticatie protocol wordt meegegeven als Base64encoded string in de HTTP Authorization header. Als schema wordt ‘Saml’ gebruikt:
Authorization: SamlYWxhZGRpbjpvcGVuc2VzYW1l....
Indien er sprake is van een workflow-ID in het token, dient dit overeen te komen met het workflow-ID van de werkstroom in het kader waarvan data uitgewisseld mogen worden. Voor sommige resources en sommige requests moet het ID van de resource worden gebruikt in de URL. Andere resources worden impliciet opgehaald met een zoekopdracht. De base van het endpoint waar resources op te halen zijn, is:
https://api.zorgplatform.online/fhir/{Version}
Response
Response
application/fhir+json
Bij een GET levert de Zorgplatform FHIR server resources op. Indien het request een individuele resource opvraagt met een resource ID, ontvangt de partnerapplicatie een resource als enkele instance. Indien het request een FHIR-search was, ontvangt de partnerapplicatie een bundle met daarin één of meerdere instanties van de opgevraagde resource. De Patient resource is een voorbeeld van een enkele resource die wordt opgeleverd.
Bij een POST ontvangt de partnerapplicatie een HTTP statuscode, een locatie en de gecreëerde resource, inclusief het toegekende ID. Het ID van de resource is later nodig indien de resource wordt geüpdatet.Zorgplatform handelt de binnengekomen resource af. In het geval van alerts wordt een actie van een zorgverlener verwacht en zal Zorgplatform de resource naar het desbetreffende zorginstelling sturen. In het informatiesysteem van de zorginstelling kan de afhandeling van een binnengekomen alert verschillend ingericht zijn,afhankelijk van de use case.
Bij een PUT maakt Zorgplatform gebruik van pessimistic locking. De partnerapplicatie ontvangt een HTTP statuscode. Zorgplatform handelt de verwerking van de resource daarna verder af.
application/fhir+json
Bij een GET levert de Zorgplatform FHIR server resources op. Indien het request een individuele resource opvraagt met een resource ID, ontvangt de partnerapplicatie een resource als enkele instance. Indien het request een FHIR-search was, ontvangt de partnerapplicatie een bundle met daarin één of meerdere instanties van de opgevraagde resource. De Patient resource is een voorbeeld van een enkele resource die wordt opgeleverd.
Bij een POST ontvangt de partnerapplicatie een HTTP statuscode, een locatie en de gecreëerde resource, inclusief het toegekende ID. Het ID van de resource is later nodig indien de resource wordt geüpdatet.Zorgplatform handelt de binnengekomen resource af. In het geval van alerts wordt een actie van een zorgverlener verwacht en zal Zorgplatform de resource naar het desbetreffende zorginstelling sturen. In het informatiesysteem van de zorginstelling kan de afhandeling van een binnengekomen alert verschillend ingericht zijn,afhankelijk van de use case.
Bij een PUT maakt Zorgplatform gebruik van pessimistic locking. De partnerapplicatie ontvangt een HTTP statuscode. Zorgplatform handelt de verwerking van de resource daarna verder af.
Foutafhandeling
Het request kan niet worden verwerkt
Er zijn geen resources beschikbaar
Er zijn velden in een resource niet gevuld
Foutafhandeling
Het request kan niet worden verwerkt
Er zijn geen resources beschikbaar
Er zijn velden in een resource niet gevuld
Hieronder staan de meest voorkomende non-happy flows beschreven.
Het request kan niet worden verwerkt
Er zijn meerdere redenen waardoor requests mogelijk niet verwerkt kunnen worden. Een aantal veel voorkomende redenen zijn:
- de headers zijn incompleet, incorrect of worden niet door Zorgplatform ondersteund;
- de assertion in de header kan niet worden verwerkt of niet worden geaccepteerd (bijvoorbeeld dooreen verlopen token of een verkeerd workflow-ID);
- de (inhoud van de) resource is incompleet, incorrect of wordt niet door Zorgplatform ondersteund;
- de benodigde informatie om dit request uit te voeren (bijvoorbeeld uit het XIS) is niet beschikbaar;
- en/ de gebruikte FHIR search criteria worden (nog) niet ondersteund door Zorgplatform.
In deze situaties geeft Zorgplatform HTTP-foutcodes terug, met waar mogelijk een FHIR OperationOutcome.
Er zijn geen resources beschikbaar
In sommige situaties is er in het XIS bepaalde informatie niet geregistreerd, aangemeld of beschikbaar op het moment van opvragen. Afhankelijk van of dit het gewenste resultaat is, bijvoorbeeld als er geen gegevens beschikbaar zijn voor deze patiënt, levert dit andere HTTP-statuscodes op.
Er zijn velden in een resource niet gevuld
In sommige situaties is er in het XIS bepaalde informatie niet geregistreerd. Dit veld kan dan niet worden gevuld in de resource.
Het request kan niet worden verwerkt
Er zijn geen resources beschikbaar
Er zijn velden in een resource niet gevuld
Hieronder staan de meest voorkomende non-happy flows beschreven.
Er zijn meerdere redenen waardoor requests mogelijk niet verwerkt kunnen worden. Een aantal veel voorkomende redenen zijn:
- de headers zijn incompleet, incorrect of worden niet door Zorgplatform ondersteund;
- de assertion in de header kan niet worden verwerkt of niet worden geaccepteerd (bijvoorbeeld dooreen verlopen token of een verkeerd workflow-ID);
- de (inhoud van de) resource is incompleet, incorrect of wordt niet door Zorgplatform ondersteund;
- de benodigde informatie om dit request uit te voeren (bijvoorbeeld uit het XIS) is niet beschikbaar;
- en/ de gebruikte FHIR search criteria worden (nog) niet ondersteund door Zorgplatform.
In deze situaties geeft Zorgplatform HTTP-foutcodes terug, met waar mogelijk een FHIR OperationOutcome.
In sommige situaties is er in het XIS bepaalde informatie niet geregistreerd, aangemeld of beschikbaar op het moment van opvragen. Afhankelijk van of dit het gewenste resultaat is, bijvoorbeeld als er geen gegevens beschikbaar zijn voor deze patiënt, levert dit andere HTTP-statuscodes op.
In sommige situaties is er in het XIS bepaalde informatie niet geregistreerd. Dit veld kan dan niet worden gevuld in de resource.