Delen via

FHIR REST API-mogelijkheden voor Azure API for FHIR

  • Artikel

In dit artikel behandelen we enkele nuances van de RESTful-interacties van Azure API for FHIR.

Voorwaardelijk maken/bijwerken

Azure API for FHIR ondersteunt maken, voorwaardelijk maken, bijwerken en voorwaardelijke updates zoals gedefinieerd door de FHIR-specificatie. Een handige header in deze scenario's is de If-Match-header . De If-Match header wordt gebruikt en valideert de versie die wordt bijgewerkt voordat de update wordt uitgevoerd. Als de ETag niet overeenkomt met de verwachte ETag, wordt het foutbericht 412 Voorwaarde is mislukt weergegeven.

Verwijderen en Voorwaardelijk verwijderen

Azure API for FHIR biedt twee verwijderingstypen. Er is Verwijderen, ook wel bekend als Hard + Voorlopig verwijderen en Voorwaardelijk verwijderen.

Verwijderen (hard + voorlopig verwijderen)

Verwijderen gedefinieerd door de FHIR-specificatie vereist dat na het verwijderen van een resource, volgende niet-versiespecifieke leesbewerkingen van een resource een 410 HTTP-statuscode retourneren. Daarom wordt de resource niet meer gevonden door te zoeken. Bovendien kunt u met Azure API for FHIR de resource volledig verwijderen (inclusief alle geschiedenis). Als u de resource volledig wilt verwijderen, kunt u de parameterinstellingen hardDelete doorgeven aan true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true). Als u deze parameter niet doorgeeft of niet instelt hardDelete op false, zijn de historische versies van de resource nog steeds beschikbaar.

Notitie

Als u alleen de geschiedenis wilt verwijderen, ondersteunt Azure API for FHIR een aangepaste bewerking met de naam $purge-history. Met deze bewerking kunt u de geschiedenis van een resource verwijderen.

Voorwaardelijk verwijderen

Met voorwaardelijk verwijderen kunt u zoekcriteria doorgeven om een resource te verwijderen. Met Voorwaardelijke verwijdering kunt u standaard één item tegelijk verwijderen. U kunt ook de _count parameter opgeven om maximaal 100 items tegelijk te verwijderen. Hieronder ziet u enkele voorbeelden van het gebruik van voorwaardelijk verwijderen.

Als u één item wilt verwijderen met voorwaardelijk verwijderen, moet u zoekcriteria opgeven die één item retourneren.

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704

U kunt dezelfde zoekopdracht uitvoeren, maar opnemen hardDelete=true om ook alle geschiedenis te verwijderen.

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true

Als u meerdere resources wilt verwijderen, neemt u de parameter op _count=100 . Met deze parameter worden maximaal 100 resources verwijderd die voldoen aan de zoekcriteria.

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100

Herstel van verwijderde bestanden

Als u de parameter hard delete niet gebruikt, moeten de record(s) in Azure API for FHIR nog steeds bestaan. De record(s) kunt u vinden door een geschiedeniszoekactie uit te voeren op de resource en te zoeken naar de laatste versie met gegevens.

Als de id van de verwijderde resource bekend is, gebruikt u het volgende URL-patroon:

<FHIR_URL>/<resource-type>/<resource-id>/_history

Bijvoorbeeld: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history

Als de id van de resource niet bekend is, voert u een geschiedeniszoekactie uit op het hele resourcetype:

<FHIR_URL>/<resource-type>/_history

Bijvoorbeeld: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history

Nadat u de record hebt gevonden die u wilt herstellen, gebruikt u de PUT bewerking om de resource opnieuw te maken met dezelfde id of gebruikt u de POST bewerking om een nieuwe resource met dezelfde gegevens te maken.

Notitie

Er is geen verlooptijd op basis van tijd voor geschiedenisgegevens/gegevens voor voorlopig verwijderen. De enige manier om geschiedenis/voorlopig verwijderde gegevens te verwijderen, is met een harde verwijdering of de opschoningsgeschiedenis.

Patch en voorwaardelijke patch

Patch is een waardevolle RESTful-bewerking wanneer u slechts een deel van de FHIR-resource hoeft bij te werken. Met patch kunt u de elementen opgeven die u wilt bijwerken in de resource zonder dat u de hele record hoeft bij te werken. FHIR definieert drie manieren om resources te patchen: JSON-patch, XML-patch en FHIRPath-patch. De FHIR-service ondersteunt zowel JSON Patch als FHIRPath Patch, samen met voorwaardelijke JSON-patch en voorwaardelijke FHIRPath-patch (waarmee u een resource kunt patchen op basis van een zoekcriterium in plaats van een resource-id). Als u enkele voorbeelden wilt doorlopen, raadpleegt u het FHIRPath Patch REST-bestand en het JSON Patch REST-bestand voor elke benadering. Lees de HL7-documentatie voor patchbewerkingen met FHIR voor meer informatie.

Notitie

Bij gebruik met PATCH STU3 en als u een geschiedenisbundel aanvraagt, wordt de gepatchte resource Bundle.entry.request.method toegewezen aan PUT. Dit komt doordat STU3 geen definitie bevat voor het PATCH werkwoord in de waardeset HTTPVerb.

Patch met FHIRPath-patch

Deze patchmethode is het krachtigst omdat deze gebruikmaakt van FHIRPath voor het selecteren van welk element u wilt gebruiken. Een veelvoorkomend scenario is het gebruik van FHIRPath Patch om een element in een lijst bij te werken zonder de volgorde van de lijst te kennen. Als u bijvoorbeeld de telecomgegevens van een patiënt wilt verwijderen zonder de index te kennen, kunt u het onderstaande voorbeeld gebruiken.

PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Inhoudstype: application/fhir+json

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "operation",
            "part": [
                {
                    "name": "type",
                    "valueCode": "delete"
                },
                {
                    "name": "path",
                    "valueString": "Patient.telecom.where(use = 'home')"
                }
            ]
        }
    ]
}

Voor alle FHIRPath-patchbewerkingen moet de application/fhir+json inhoudstypeheader zijn ingesteld. FHIRPatch Patch ondersteunt bewerkingen voor toevoegen, invoegen, verwijderen, verwijderen en verplaatsen. FHIRPatch Patch-bewerkingen kunnen ook eenvoudig worden geïntegreerd in Bundels. Bekijk het FHIRPath Patch REST-voorbeeldbestand voor meer voorbeelden.

Patch met JSON-patch

JSON Patch in de FHIR-service voldoet aan de goed gebruikte specificatie die is gedefinieerd door de Internet Engineering Task Force. De nettoladingindeling maakt geen gebruik van FHIR-resources en gebruikt in plaats daarvan een JSON-document dat gebruikmaakt van JSON-Pointers voor de selectie van elementen. JSON Patch is compacter en heeft een testbewerking waarmee u kunt valideren of een voorwaarde waar is voordat u de patch uitvoert. Als u een patiënt bijvoorbeeld alleen als overleden wilt instellen als deze nog niet als overleden is gemarkeerd, kunt u het onderstaande voorbeeld gebruiken.

PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Inhoudstype: application/json-patch+json

[
	{
		"op": "test",
		"path": "/deceasedBoolean",
		"value": false
	},
	{
		"op": "replace",
		"path": "/deceasedBoolean",
		"value": true
	}
]

Voor alle JSON-patchbewerkingen moet de application/json-patch+json header Content-Type zijn ingesteld. JSON Patch ondersteunt bewerkingen voor toevoegen, verwijderen, vervangen, kopiëren, verplaatsen en testen. Bekijk het JSON Patch REST-voorbeeldbestand voor meer voorbeelden.

JSON-patch in bundels

Standaard wordt JSON Patch niet ondersteund in Bundelresources. Dit komt doordat een bundel alleen ondersteuning biedt voor FHIR-resources en de nettolading van de JSON-patch geen FHIR-resource is. Om dit te omzeilen, gebruiken we binaire resources met een inhoudstype van "application/json-patch+json" en de base64-codering van de JSON-nettolading in een bundel. Bekijk dit onderwerp op de FHIR Chat Zulip voor informatie over deze tijdelijke oplossing.

In het onderstaande voorbeeld willen we het geslacht van de patiënt wijzigen in vrouwelijk. We hebben de JSON-patch [{"op":"replace","path":"/gender","value":"female"}] genomen en gecodeerd naar base64.

VERZENDEN https://{FHIR-SERVICE-HOST-NAME}/
Inhoudstype: application/json

{
	"resourceType": "Bundle",
	"id": "bundle-batch",
	"type": "batch",
	"entry": [
		{
			"fullUrl": "Patient/{PatientID}",
			"resource": {
				"resourceType": "Binary",
				"contentType": "application/json-patch+json",
				"data": "W3sib3AiOiJyZXBsYWNlIiwicGF0aCI6Ii9nZW5kZXIiLCJ2YWx1ZSI6ImZlbWFsZSJ9XQ=="
			},
			"request": { 
				"method": "PATCH",
				"url": "Patient/{PatientID}"
			}
		}
	]
}

Volgende stappen

In dit artikel hebt u kennisgemaakt met enkele van de REST-mogelijkheden van Azure API for FHIR. Vervolgens vindt u meer informatie over de belangrijkste aspecten van het zoeken naar resources in FHIR.

Overzicht van zoeken in Azure API for FHIR

(FHIR®) is een gedeponeerd handelsmerk van HL7 en wordt gebruikt met de toestemming van HL7.