# Patching

SanteDB's REST API supports patching of resources. Patching follows [IETF RFC 5789](https://tools.ietf.org/html/rfc5789) pattern and has the following rules:

* The patch must be applied to a specific instance of a resource
* The patch must include the If-Match header with the etag of the last version the client has (and wishes to patch)

### Constructing a Patch

The format of a patch in SanteDB is illustrated below:

```markup
<Patch xmlns="http://santedb.org/model">
    <appliesTo type="Patient|Place|Entity...">
        <id>9fdb557d-2e2f-4fe5-a193-e1cf8cf49bc4</id>
    </appliesTo>
    <change op="Test|Replace|Remove|Add" path="pathInObject">
        <value>
            object
        </value>
    </change>
</Patch>
```

For example, if we wanted to replace the Legal name of a patient, the patch would be as follows:

```markup
<Patch xmlns="http://santedb.org/model">
    <appliesTo type="Patient">
        <id>1c8c9aa3-abb8-48ee-992d-8f0c524ce40c</id>
    </appliesTo>
    <!-- Remove existing Legal Name -->
    <change op="Remove" path="name">
        <value>
            <EntityName>
                <use>effe122d-8d30-491d-805d-addcb4466c35</use>
            </EntityName>
        </value>
    </change>
    <change op="Add" path="name">
        <value>
            <EntityName>
                <use>effe122d-8d30-491d-805d-addcb4466c35</use>
                <component>
                    <value>Jim</value>
                </component>
            </EntityName>
    </change>
</Patch>
```

Alternately you can simply identify a specific instance to be removed by substituting the use qualifier with a UUID:

```markup
<change op="Remove" path="name">
    <value>9fdb557d-2e2f-4fe5-a193-e1cf8cf49bc4</value>
</change>
```

Which removes a name with ID : 9fdb557d-2e2f-4fe5-a193-e1cf8cf49bc4 from the patient's name list then replaces it.

You can also patch using JSON, for example, the following patch will remove the tag "favoriteColour" and replace it:

```javascript
{
    "$type": "Patch",
    "appliesTo": {
        "type": "Patient",
        "id": "9fdb557d-2e2f-4fe5-a193-e1cf8cf49bc4"
    },
    "change": [
        {
            "$type": "PatchOperation",
            "path": "tag",
            "op": "Remove",
            "value": {
                "$type": "EntityTag",
                "key": "favoriteColor"
            }
        },
        {
            "$type": "PatchOperation",
            "path": "tag",
            "op": "Add",
            "value": {
                "$type": "EntityTag",
                "key": "favoriteColor",
                "value": "Blue"
            }
        }
    ]
}                
```

### Dealing with Conflicts

You can assert that particular values are present or true prior to performing your patch, additionally the SanteDB service will assert on the etag of the `If-Match` header. For example, this patch will change the gender of the patient from MALE to FEMALE, but will only succeed if the etag matches `e15be5a372b742ccac35518df7c9a784` and the gender is currently MALE.

```http
PATCH /hdsi/Patient/9fdb557d-2e2f-4fe5-a193-e1cf8cf49bc4 HTTP/1.1
If-Match: e15be5a372b742ccac35518df7c9a784
Content-Type: application/json

{
    "$type": "Patch",
    "appliesTo": {
        "type": "Patient",
        "id": "9fdb557d-2e2f-4fe5-a193-e1cf8cf49bc4"
    },
    "change": [
        {
            "$type": "PatchOperation",
            "op": "Test",
            "path": "genderConcept",
            "value": "f4e3a6bb-612e-46b2-9f77-ff844d971198"
        },
        {
            "$type": "PatchOperation",
            "path": "genderConcept",
            "op": "Replace",
            "value": "094941e9-a3db-48b5-862c-bc289bd7f86c"
        }
    ]
}             
```

If the server does not have the same copy of the patient, then an HTTP 409 (CONFLICT) is returned to the caller.&#x20;

You may override (or force) the patch to occur by using these sets of headers:

```http
PATCH /hdsi/Patient/9fdb557d-2e2f-4fe5-a193-e1cf8cf49bc4
If-Match: e15be5a372b742ccac35518df7c9a784
Content-Type: application/json
X-Patch-Force: true
```

Which will bypass the outcomes of checks.

{% hint style="info" %}
It is best practice to not append the X-Patch-Force header **unless** a human is indicating that they would like to force the the patch to succeed.
{% endhint %}

### Difference Operation

You can submit an object to the SanteDB API to get a "diff" of two objects. This operation is invoked using the `$diff` operation on the desired instance of the type. For example, to see the instructions it would take to turn patent `9fdb557d-2e2f-4fe5-a193-e1cf8cf49bc4` to `1c8c9aa3-abb8-48ee-992d-8f0c524ce40c` submitting the following request.

```http
POST /hdsi/Patient/9fdb557d-2e2f-4fe5-a193-e1cf8cf49bc4/$diff HTTP/1.1
Content-Type: application/json

{
    "$type":"ApiOperationParameterCollection",
    "parameter": [
        {
            "name":"other",
            "value": "1c8c9aa3-abb8-48ee-992d-8f0c524ce40c"
        }
    ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.santesuite.org/developers/service-apis/health-data-service-interface-hdsi/patching.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.