Partial update of an OSLC resource

Edit online

The HTTP PATCH method updates part of an OSLC resource. Unlike the PUT method, the PATCH method does not delete local resource properties that are not included in the request. The x-method-override header is required to implement the PATCH method.

When you use the PATCH method to replace an OSLC resource, the following rules apply:

  • 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 explicitly affected by the request. However, literal properties can be implicitly affected by the business logic that is associated with the resource.
  • Local resource properties are updated or replaced if there are corresponding property values in the PATCH request. If a resource property is not included in the request, the corresponding local resource is not explicitly affected by the request. If a resource property is included in the request, the incoming value replaces or updates the value in the server.
  • You cannot explicitly update reference resources but you can update properties that refer to the resource, and the properties follow the update model of literal properties.

HTTP PATCH requests are used in the following scenarios:

  • The PATCH request replaces an array (local resource) property with the content in the request. This scenario is the default implementation.
  • You can find and match array resource elements from the request with corresponding resource elements on the server. Depending on whether a match is found, the array resource elements are updated or inserted. An array element is never deleted from the local resource property. To use a PATCH request to match array elements, the consumer application sets the PATCHTYPE HTTP request header to the value MERGE (case sensitive).

Example: Updating a literal property

The following method updates the title property of a work order: 
POST /maximo/oslc/os/oslcwodetail/abcd
x-method-override: PATCH

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

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

Example: Updating and merging a resource property

The following method updates the resource with the PATCHTYPE header set to MERGE: 
POST /maximo/oslc/os/oslcwodetail/abcd
x-method-override: PATCH
PATCHTYPE: MERGE

{
   "dcterms:title": "Check-out Leaking – Modified for Test",
    “spi:wplabor”: [
	{
		 “spi_wm:wplaborid": "0000000067",
 "spi_wm:rate": 18.5
            }
]
}

The request initiates a search for a wplabor record with the ID 0000000067. If such a wplabor record exists, the record is updated. If no match is found, a new wplabor record is created with the ID 0000000067. Because the PATCHTYPE header is set to MERGE, the other wplabor records for this work order resource remain unchanged.

Example: Making a conditional update

The following method updates the resource if the ETag value is 1234567: 
POST /maximo/oslc/os/oslcwodetail/abcd
x-method-override: PATCH
if-match: 1234567

If the ETag value is 1234567, the work order resource is updated and an HTTP 204 response is sent to the consumer application.

If the ETag value is not 1234567, the server responds with an HTTP 412 Precondition failed message. This message indicates that the resource was updated by some other process and the requesting consumer application has an out-of-date copy of the resource. The consumer application must perform a GET request on the abcd resource to get a fresh copy of the resource.