tencent cloud

Tencent Healthcare Data Services

문서Tencent Healthcare Data ServicesAPI DocumentationResource Basic Operation APIsPatches

Patches

Download
포커스 모드
폰트 크기
마지막 업데이트 시간: 2026-08-28 16:06:55
AI 번역

API Description

This is used to perform partial updates on specified resources. This API follows the standard FHIR Patch operation. The client submits a patch document via the HTTP PATCH method, modifying only specific fields within the resource without requiring the full resource content.
This API supports the JSON Patch-based update method. The Content-Type request header typically uses application/json-Patch+json. The Patch document is submitted as an array, with each item representing a change operation. Common operations include:
add: Adds a field or an array element.
replace: Replaces the value of an existing field.
remove: Deletes a field or an array element.
test: Verifies whether the current value at the target path meets expectations. It is commonly used for conditional checks before a deletion is performed.

Input parameters

Parameter Name
Type
Required
Description
HTTP Method
String
Yes
Fixed as PATCH.
URL
String
Yes
The address for partially updating a resource, in the format [baseUrl]/[resourceType]/[id].
Authorization
String
Yes
The authentication token, in the format Bearer <AccessToken>. The AccessToken is obtained via the GetAccessToken API in Calling Methods (or via the GetWebAccessToken API in the instance console scenario).
Content-Type
String
Yes
The MIME type of the request body, fixed as application/json-patch+json.
Request Body
JSON Array
Yes
A JSON Patch document, where each element in the array represents an operation.
Path Parameter Description:
Field
Type
Required
Description
resourceType
String
Yes
The FHIR resource type. In this example, it is Patient. To view all resource types actually supported by the current instance, call the CapabilityStatement API via GET /INSTANCE_ID/fhir/metadata and check the returned rest[].resource[].type (the resource types supported by an instance can be configured and trimmed during creation via supported_resource_types, which may vary across instances). For field definitions of each resource type, refer to FHIR Resource Types.
id
String
Yes
The unique ID of the resource. It is the logical ID automatically assigned by the server when the resource is created, and can be obtained in the following ways:
Call the Create API (POST) to create a resource. Obtain the resource identifier from the Content-Location response header or the id field in the response body.
Call the Search API (GET /[resourceType]?_id= or /[resourceType]?identifier=) to query for existing resource IDs.
Request URL Example:
https://HOSTNAME/INSTANCE_ID/fhir/Patient/149954
Request Body Example Field Descriptions:
Field
Type
Required
Description
op
String
Yes
Patch operation types, such as add, replace, remove, and test.
path
String
Yes
The target path for the change, which uses the JSON Pointer format, such as /gender.
value
Any
No
The value to be changed. Usually required for add and replace operations.
Note:
The patch document must be an array. You must use the array format even if the document contains only a single operation.
When adding to an array field, if the target array does not exist, you typically need to first create the array node and then write content to the specified index.
path must accurately point to the target field within the resource. Otherwise, the request may fail.
When deleting an array element, you must specify the array index of the element to be deleted, for example, /address/0.
To avoid accidental deletion, you can first use the test operation to verify the content of the target element, and then perform the remove operation.

Output Parameters

Upon a successful API call, the HTTP status code 200 OK is typically returned. The response headers contain the resource version information and the latest version URL, while the response body returns the latest resource content after the patch is applied.
Response Header Example Description:
Parameter Name
Type
Description
Status Code
Integer
Returns 200 OK when successful.
Content-Location
String
The historical version address of the updated resource, in the format [baseUrl]/[resourceType]/[id]/_history/[versionId].
Last-Modified
String
The last modification time of the resource, in the HTTP-date format, for example Mon, 06 Jul 2026 08:42:36 GMT.
Key Response Body Field Descriptions:
Field
Type
Description
resourceType
String
Resource type
id
String
Unique ID of the updated resource.
meta.versionId
String
Version ID of the current resource.
meta.lastUpdated
String
Last update time of the resource.
meta.source
String
Identifier of the resource source, returned only when this field was specified during resource creation/update.
gender
String
Updated gender field (this example uses the Patient resource).
birthDate
String
Updated birth date (this example uses the Patient resource).
address
Array
Updated address information (this example uses the Patient resource).
Note:
Whether the text field (Narrative summary) is included in the response body depends on the server's Narrative configuration. When the configuration is enabled (narrative_enabled=true), the text.status and text.div fields are returned. When the configuration is disabled, the text field is not returned.
The possible values for text.status are generated, extensions, additional, and empty.
The meta.source field is returned only if it was specified during resource creation or update. This field is used to identify the original source system of the resource. It can be set via the X-Source request header (which requires the server to enable the CaptureResourceSourceFromHeaderInterceptor) or by the client directly writing to meta.source.
The fields gender, birthDate, and address in the table above are example fields for the Patient resource. The actual business fields in the response body depend on the type of resource being patched and the modifications made.

Examples

Example 1: Adding a Gender Field

Request Example

PATCH /INSTANCE_ID/fhir/Patient/149954 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <token>
Content-Type: application/json-patch+json
[
  {
    "op": "add",
    "path": "/gender",
    "value": "female"
  }
]

Response Example

HTTP/1.1 200 OK
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Patient/149954/_history/2
Last-Modified: Mon, 06 Jul 2026 08:42:36 GMT
{
  "resourceType": "Patient",
  "id": "149954",
  "meta": {
    "versionId": "2",
    "lastUpdated": "2022-04-24T19:05:13.111+05:30"
  },
  "gender": "female"
}

Example 2: Adding Address Information

Request Example

PATCH /INSTANCE_ID/fhir/Patient/149954 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <token>
Content-Type: application/json-patch+json
[
  {
    "op": "add",
    "path": "/address",
    "value": []
  },
  {
    "op": "add",
    "path": "/address/0",
    "value": {
      "use": "home",
      "line": [
        "<Sample Street Name>",
        "avon"
      ],
      "city": "<City_Name>",
      "district": "<Sample Street Name>",
      "state": "Vic",
      "postalCode": "3999",
      "text": "<Sample Street Name>"
    }
  }
]

Response Example

HTTP/1.1 200 OK
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Patient/149954/_history/3
Last-Modified: Mon, 06 Jul 2026 08:42:36 GMT
{
  "resourceType": "Patient",
  "id": "149954",
  "meta": {
    "versionId": "3",
    "lastUpdated": "2022-04-24T19:17:02.229+05:30"
  },
  "gender": "female",
  "address": [
    {
      "use": "home",
      "text": "<Sample Street Name>",
      "line": [
        "<Sample Street Name>",
        "avon"
      ],
      "city": "<City_Name>",
      "district": "<Sample Street Name>",
      "state": "Vic",
      "postalCode": "3999"
    }
  ]
}

Example 3: Replacing Zip Code and Date of Birth

Request Example

PATCH /INSTANCE_ID/fhir/Patient/149954 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <token>
Content-Type: application/json-patch+json
[
  {
    "op": "replace",
    "path": "/address/0/postalCode",
    "value": "4000"
  },
  {
    "op": "replace",
    "path": "/birthDate",
    "value": "1974-02-20"
  }
]

Response Example

HTTP/1.1 200 OK
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Patient/149954/_history/4
Last-Modified: Mon, 06 Jul 2026 08:42:36 GMT
{
  "resourceType": "Patient",
  "id": "149954",
  "meta": {
    "versionId": "4",
    "lastUpdated": "2022-04-24T19:37:51.559+05:30"
  },
  "gender": "female",
  "birthDate": "1974-02-20",
  "address": [
    {
      "use": "home",
      "text": "<Sample Street Name>",
      "line": [
        "<Sample Street Name>",
        "avon"
      ],
      "city": "<City_Name>",
      "district": "<Sample Street Name>",
      "state": "Vic",
      "postalCode": "4000"
    }
  ]
}

Example 4: Deleting the First Element in the Address Array

Request Example

PATCH /INSTANCE_ID/fhir/Patient/149954 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <token>
Content-Type: application/json-patch+json
[
  {
    "op": "remove",
    "path": "/address/0"
  }
]

Response Example

HTTP/1.1 200 OK
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Patient/149954/_history/5
Last-Modified: Mon, 06 Jul 2026 08:42:36 GMT
{
  "resourceType": "Patient",
  "id": "149954",
  "meta": {
    "versionId": "5",
    "lastUpdated": "2022-04-24T19:54:03.769+05:30"
  },
  "gender": "female",
  "birthDate": "1974-02-20"
}
Note:
When the target field is an array, you must specify the position of the array element to perform a deletion. If you cannot confirm whether the current position still contains the target data, it is recommended to first use the test operation to verify the content.
If the array becomes empty after deletion (meaning the original array had only one element), and the instance has repository validation enabled (enable_repository_validating_interceptor=true), you must handle the empty array and meta.source issues. See Example Six.

Example 5: Deleting Address Information After Verification

Request Example

PATCH /INSTANCE_ID/fhir/Patient/149954 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <token>
Content-Type: application/json-patch+json
[
  {
    "op": "test",
    "path": "/address/0",
    "value": {
      "use": "home",
      "line": [
        "<Sample Street Name>",
        "avon"
      ],
      "city": "<City_Name>",
      "district": "<Sample Street Name>",
      "state": "Vic",
      "postalCode": "4000",
      "text": "<Sample Street Name>"
    }
  },
  {
    "op": "remove",
    "path": "/address/0"
  }
]

Response Example

HTTP/1.1 200 OK
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Patient/149954/_history/5
Last-Modified: Mon, 06 Jul 2026 08:42:36 GMT
{
  "resourceType": "Patient",
  "id": "149954",
  "meta": {
    "versionId": "5",
    "lastUpdated": "2022-04-24T19:54:03.769+05:30"
  },
  "gender": "female",
  "birthDate": "1974-02-20"
}

Example 6: Clearing Array Fields When Data Validation Is Enabled

Request Example

PATCH /INSTANCE_ID/fhir/Patient/149954 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <token>
Content-Type: application/json-patch+json
[
  {
    "op": "replace",
    "path": "/meta/source",
    "value": "http://test.example.com/source"
  },
  {
    "op": "remove",
    "path": "/address/0"
  },
  {
    "op": "remove",
    "path": "/address"
  }
]

Response Example

HTTP/1.1 200 OK
Content-Location: https://HOSTNAME/INSTANCE_ID/fhir/Patient/149954/_history/2
Last-Modified: Mon, 14 Jul 2026 12:17:58 GMT
{
  "resourceType": "Patient",
  "id": "149954",
  "meta": {
    "versionId": "2",
    "lastUpdated": "2026-07-14T20:17:58.710+08:00",
    "source": "http://test.example.com/source#rdVXtMxLI6QB74gC"
  },
  "identifier": [
    {
      "system": "http://test.example.com/patient-id",
      "value": "TEST-001"
    }
  ],
  "name": [
    {
      "family": "Test",
      "given": ["Validate"]
    }
  ],
  "gender": "male",
  "birthDate": "2000-01-01"
}
Note:
When an instance has Repository Validation enabled (enable_repository_validating_interceptor=true, which is enabled by default in production environments), the resource after a PATCH operation is fully validated by the FHIR RepositoryValidatingInterceptor.
The first operation, replace /meta/source, changes the source to a valid URL. By default, HAPI constructs the requestId as #requestId and writes it to meta.source. A pure fragment does not comply with URI specifications and must be replaced with a valid URL.
The second operation, remove /address/0, deletes an array element.
The third operation, remove /address, deletes the empty array field itself to avoid leaving an empty array [].
If the instance does not have repository validation enabled, you only need to perform the second step, remove (see Example Four).

Error Codes

Common error codes are listed below. For more error codes, see Error Codes.
Error Code
Description
400 Bad Request
Malformed patch document, or invalid path and op parameters.
401 Unauthorized
Not authenticated, and valid credentials are missing.
403 Forbidden
Authenticated but not authorized to update the resource.
404 Not Found
The specified resource does not exist.
409 Conflict
Resource state conflict, for example, the target path does not match the current resource state.
412 Precondition Failed
The resource failed the data validation by RepositoryValidatingInterceptor. Common cause: An empty array field appears after a PATCH operation is applied (for example, the entire address array is not removed after remove /address/0).
415 Unsupported Media Type
The Content-Type is not supported, for example, application/json-patch+json is not used.
422 Unprocessable Entity
The patch syntax is correct, but it fails business or FHIR rule validation.
500 Internal Server Error
Internal server processing exception.

이전 주제: Delete다음 주제: Read

도움말 및 지원

문제 해결에 도움이 되었나요?

피드백