HTTP PATCH method

PATCH is used for a partial update of an OSLC resource. A PATCH does not delete any local resource properties that are not included in the request. The PATCH request is sent by a POST method with the x-method-override header set to PATCH.

The following rules apply when you use a PATCH to replace an OSLC resource:

  • All literal properties that are specified in the request document are updated. Any literal property that is not specified as part of the request is not impacted explicitly. However, it can be implicitly impacted by the business logic that is attached to the resource. This rule is the same as when you use the PUT method to replace a resource.
  • All local resource properties are updated or replaced by corresponding property values from the request. If the resource property is not included in the request, the corresponding local resource is not explicitly impacted. If the resource property is included, its value replaces or updates the value in the server. Other resource properties are deleted by a PATCH and not deleted by a MERGE.
  • Reference resources cannot be updated explicitly. However, you can update properties that refer to the resource, and the properties follow the update model of literal properties. This rule is the same as when you use the PUT method to replace a resource.

Example: Updating a literal property

The following method updates the task name property of the work task: 
POST http://yourserver/oslc/so/WorkTask/123
x-method-override: PATCH

{
   "dcterms:taskname": "Check-out Leaking – Modified for Test"
}

Unlike the PUT method, this PATCH method does not update other properties of the work task.

Example: Updating a local resource property

The following method updates a specified parts record and deletes other data: 
POST http://yourserver/oslc/so/WorkTask/123
x-method-override: PATCH

{
   "dcterms:taskname": "Check-out Leaking – Modified for Test",
    “spi:parts”: [
	{
		 “spi:partsid": "0000000067",
 "spi:quantity": 5
            }
]
}

This method behaves similarly to the PUT method. The system searches for a parts record with the ID 0000000067. If such a parts record exists, it is updated. If no match is found, a new parts record is created. All other parts records for this work task resource are deleted.

Example: Updating and merging a local resource property

The following method updates the resource with the PATCHTYPE header set to MERGE: 
POST http://yourserver/oslc/so/WorkTask/123
x-method-override: PATCH
PATCHTYPE: MERGE

{
   "dcterms:taskname": "Check-out Leaking – Modified for Test",
    “spi:parts”: [
	{
		 “spi:partsid": "0000000067",
 "spi:quantity": 5
            }
]
}

A search is made for a parts record with the ID 0000000067. If such a parts record exists, it is updated. If no match is found, a new parts record is created. Because the PATCHTYPE header is set to MERGE, the other parts records for this work task resource are left intact.

Example: Making a conditional update

The following method updates the resource if the ETag value is 1376596202470: 
POST http://yourserver/oslc/so/WorkTask/123
x-method-override: PATCH
if-match: 1376596202470

If the ETag value is 1376596202470, the work task resource is updated and an HTTP 204 message is sent.

If the ETag value is not 1376596202470, the server responds with an HTTP 412 Precondition failed message. This message implies that the resource was updated by some other process and the requesting client has a stale copy of the resource. The client must perform a GET method on the 123 resource to get a fresh copy of the resource.

The following table summarizes the result of each update method when applied to different types of resources.
Method Literal properties Local resources Reference resources
PUT If omit a property, the property is not affected. If omit a property, the property is deleted. If omit a property, the property is not affected.
PATCH If omit a property, the property is not affected. If omit a property, the property is not affected. If omit a property, the property is not affected.
MERGE If omit a property, the property is not affected. If omit a property, the property is not affected. If omit a property, the property is not affected.