|
| 1 | +--- |
| 2 | +title: FHIR Rest API capabilities for Azure API for FHIR |
| 3 | +description: This article describes the RESTful interactions and capabilities for Azure API for FHIR. |
| 4 | +author: stevewohl |
| 5 | +ms.service: healthcare-apis |
| 6 | +ms.subservice: fhir |
| 7 | +ms.topic: conceptual |
| 8 | +ms.date: 09/28/2021 |
| 9 | +ms.author: cavoeg |
| 10 | +--- |
| 11 | + |
| 12 | +# FHIR Rest API capabilities for Azure API for FHIR |
| 13 | + |
| 14 | +In this article, we'll cover some of the nuances of the RESTful interactions of Azure API for FHIR. |
| 15 | + |
| 16 | + |
| 17 | +## Conditional create/update |
| 18 | + |
| 19 | +Azure API for FHIR supports create, conditional create, update, and conditional update as defined by the FHIR specification. One useful header in these scenarios is the [If-Match](https://www.hl7.org/fhir/http.html#concurrency) header. The `If-Match` header is used and will validate the version being updated before making the update. If the `ETag` doesn’t match the expected `ETag`, it will produce the error message *412 Precondition Failed*. |
| 20 | + |
| 21 | +## Delete |
| 22 | + |
| 23 | +[Delete](https://www.hl7.org/fhir/http.html#delete) defined by the FHIR specification requires that after deleting, subsequent non-version specific reads of a resource returns a 410 HTTP status code, and the resource is no longer found through searching. Additionally, Azure API for FHIR enables you to fully delete (including all history) the resource. To fully delete the resource, you can pass a parameter settings `hardDelete` to true (`DELETE {server}/{resource}/{id}?hardDelete=true`). If you don't pass this parameter or set `hardDelete` to false, the historic versions of the resource will still be available. |
| 24 | + |
| 25 | +> [!NOTE] |
| 26 | +> If you want to delete only the history, Azure API for FHIR supports a custom operations, `$purge-history`, which allows you to delete the history off of a resource. |
| 27 | +
|
| 28 | +## Conditional delete |
| 29 | + |
| 30 | +In addition to delete, Azure API for FHIR supports conditional delete, which allows you to pass a search criteria to delete a resource. By default, the conditional delete will allow you to delete one item at a time. You can also specify the `_count` parameter to delete up to 100 items at a time. Below are some examples of using conditional delete. |
| 31 | + |
| 32 | +To delete a single item using conditional delete, you must specify search criteria that returns a single item. |
| 33 | + |
| 34 | +DELETE `https://{{hostname}}/Patient?identifier=1032704` |
| 35 | + |
| 36 | +You can do the same search but include hardDelete=true to also delete all history. |
| 37 | + |
| 38 | +DELETE `https://{{hostname}}/Patient?identifier=1032704&hardDelete=true` |
| 39 | + |
| 40 | +If you want to delete multiple resources, you can include `_count=100`, which will delete up to 100 resources that match the search criteria. |
| 41 | + |
| 42 | +DELETE `https://{{hostname}}/Patient?identifier=1032704&_count=100` |
| 43 | + |
| 44 | +## Patch and Conditional Patch |
| 45 | + |
| 46 | +Patch is a valuable RESTful operation when you need to update only a portion of the FHIR resource. Using Patch allows you to specify the element(s) that you want to update in the resource without having to update the entire record. FHIR defines three types of ways to Patch resources in FHIR: JSON Patch, XML Patch, and FHIR Path Patch. The FHIR service supports JSON Patch and Conditional JSON Patch (which allows you to Patch a resource based on a search criteria instead of an ID). To walk through some examples of using JSON Patch, refer to the sample [REST file](https://github.com/microsoft/fhir-server/blob/main/docs/rest/PatchRequests.http). |
| 47 | + |
| 48 | +### Testing Patch |
| 49 | + |
| 50 | +Within Patch, there is a test operation that allows you to validate that a condition is true before doing the patch. For example, if you wanted to set a patient deceased, only if they were not already marked as deceased, you could use the example below: |
| 51 | + |
| 52 | +PATCH `http://{FHIR-SERVICE-NAME}/Patient/{PatientID}` |
| 53 | +Content-type: `application/json-patch+json` |
| 54 | + |
| 55 | +``` |
| 56 | +[ |
| 57 | + { |
| 58 | + “op”: “test”, |
| 59 | + “path”: “/deceasedBoolean”, |
| 60 | + “value”: false |
| 61 | + }, |
| 62 | + { |
| 63 | + “op”: “replace” |
| 64 | + “path”: “/deceasedBoolean”, |
| 65 | + “value”: true |
| 66 | + } |
| 67 | +] |
| 68 | +
|
| 69 | +``` |
| 70 | + |
| 71 | +### Patch in Bundles |
| 72 | + |
| 73 | +By default, JSON Patch is not supported in Bundle resources. This is because a Bundle only supports with FHIR resources and JSON Patch is not a FHIR resource. To work around this, we'll treat Binary resources with a content-type of `"application/json-patch+json"`as base64 encoding of JSON string when a Bundle is executed. For information about this workaround, log in to [Zulip](https://chat.fhir.org/#narrow/stream/179166-implementers/topic/Transaction.20with.20PATCH.20request). |
| 74 | + |
| 75 | +In the example below, we want to change the gender on the patient to female. We have taken the JSON patch `[{"op":"replace","path":"/gender","value":"female"}]` and encoded it to base64. |
| 76 | + |
| 77 | +POST `https://{FHIR-SERVICE-NAME}/` |
| 78 | +content-type: `application/json` |
| 79 | + |
| 80 | +``` |
| 81 | +{ |
| 82 | + “resourceType”: “Bundle” |
| 83 | + “id”: “bundle-batch”, |
| 84 | + “type”: “batch” |
| 85 | + “entry”: [ |
| 86 | + { |
| 87 | + “fullUrl”: “Patient/{PatientID}”, |
| 88 | + “resource”: { |
| 89 | + “resourceType”: “Binary”, |
| 90 | + “contentType”: “application/json-patch+json”, |
| 91 | + “data”: "W3sib3AiOiJyZXBsYWNlIiwicGF0aCI6Ii9nZW5kZXIiLCJ2YWx1ZSI6ImZlbWFsZSJ9XQ==" |
| 92 | + }, |
| 93 | + “request”: { |
| 94 | + “method”: “PATCH”, |
| 95 | + “url”: “Patient/{PatientID}” |
| 96 | + } |
| 97 | + } |
| 98 | + ] |
| 99 | +} |
| 100 | +
|
| 101 | +``` |
| 102 | + |
| 103 | +## Next steps |
| 104 | + |
| 105 | +In this article, you learned about some of the REST capabilities of Azure API for FHIR. Next, you can learn more about the key aspects to searching resources in FHIR. |
| 106 | + |
| 107 | +>[!div class="nextstepaction"] |
| 108 | +>[Overview of search in Azure API for FHIR](overview-of-search.md) |
0 commit comments