REST API for Common Features in Oracle Fusion Cloud Applications

Verify Resource Updates Using the ETag Value

Verifying changes to a resource can be a time-consuming and bandwidth-intensive task for a REST client. To save processing time and payload size, use the Entity Tag (ETag) to conditionally retrieve the resource stored with the client, and verify it for any modifications. You can find the ETag as the http response header.

The ETag value can be used along with the If-None-Match or If-Match conditional request headers to get the status. The If-None-Match header is generally used with a GET request to verify any changes to the resource. The If-Match header is used with a PATCH request to update a resource assuming there's no change in the resource since the time the last GET request was sent.

The following table lists the different responses that you can expect if you use the ETag value with these headers.

HTTP Method	HTTP Request Header	Resource Modified	Resource Not Modified
GET	If-None-Match	Status: 200 OK 200 is returned to indicate that the requested resource is modified, and the requested resource is returned. The updated information is provided in the response body.	Status: 304 Not modified 304 is returned to indicate that the requested resource is not modified. An empty response is returned in the response body.
PATCH	If-Match	Status: 412 Precondition Failed Request fails.	Status: 200 OK The request is processed, and the updated information is provided in the response body.

HTTP Method

HTTP Request Header

Resource Modified

Resource Not Modified

GET

If-None-Match

Status: 200 OK

200 is returned to indicate that the requested resource is modified, and the requested resource is returned.

The updated information is provided in the response body.

Status: 304 Not modified

304 is returned to indicate that the requested resource is not modified.

An empty response is returned in the response body.

PATCH

If-Match

Status: 412 Precondition Failed

Request fails.

Status: 200 OK

The request is processed, and the updated information is provided in the response body.

Note:

You can use the If-None-Match and If-Match headers only for a singular resource.

The position of the ETag header in the response body may vary based on the REST Framework Version. If you're using Framework Version 6 and above, you can find the ETag in the @context section of the response. For more information, see topic Set the REST Framework Version.

Let's now look at how to retrieve the ETag value and use it in a subsequent request to either get new content or update the resource.

Send a GET request to get the ETag value. For a GET operation on a singular resource, you'll find the ETag in both the http request response header and the response body.

In this example, we're trying to get the ETag value using the GET request on a singular resource.

Request

GET /hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005

Response

The ETag value in the response body is used in the next step to verify if there are any changes in the resource.

"DisplayName": "Erin Mack",
"@context": {
        "key": "180511",
        "headers": {
          "ETag": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000478"
        },
  "links": [
    {
      "rel": "self",
      "href": "https://<host>:<port>/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005/ ",
      "name": "names",
      "kind": "item",
      "properties": {
      }
    }
  ]
}

In this example, we're trying to get the ETag value using the GET request on a collection resource.

Request

GET /hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005

Response

{
  "items": [
   {
     "DisplayName": "Erin Mack",
     "@context": {
        "key": "180511",
        "headers": {
          "ETag": FCED00057372000000014770400000014737A76612E6C616E672E4"
        },
  "links": [
    {
      "rel": "self",
      "href": "https://<host>:<port>/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005/ ",
      "name": "names",
      "kind": "item",
      "properties": {
      }
    }
  ]
}

Note:

In the response body, you'll notice that each resource item has its own ETag value that you can use to verify and update a particular resource, using a separate request.

Use the ETag value in the subsequent requests to check for existing updates or update the resource.
- Send a GET request using the value in the ETag, along with the If-None-Match header to get the new content if the resource is modified.
  Request
```
GET /hcmRestApi/resources/11.13.18.05/workers/00020000000EACED00057708000000005
If-None-Match: "<etag_value>"
```
  Response
```
304 Not modified
```
  If the resource wasn't modified, the server acknowledges the request and returns the status 304 Not Modified. Since there's no change, there's no response body.
  
  If the resource is changed, the response body contains the updated information and the new ETag value.
```
200 OK
{
  "DisplayName": "Erin D Mack",
"@context": {
        "key": "180511",
        "headers": {
          "ETag": "FCED00057372000000014770400000014737A76612E6C616E672E4"
        },
  "links": [
    {
      "rel": "self",
      "href": "https://<host>:<port>/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005/ ",
      "name": "names",
      "kind": "item",
      "properties": {
      }
    }
  ]
}
```
- Send a PATCH request to verify and update a resource, assuming there's no change in the resource since the time the last GET request was sent. In this case, you can use the If-Match header along with the ETag value retrieved in the last GET request.
  Request
```
PATCH https://servername.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/Departments/10 
If-Match:"<etag_value>"
```
  Response
  
  If the resource isn't updated, then the ETag value passed in the request matches the current value on the server and the update request is processed. The response displays the status 200 message with the response body displaying the updated detail and a new ETag value for subsequent use.
```
200 OK
```
  If the value of the ETag in the request is different from what's on the server, that means some other request has recently modified this resource. Therefore, this update can't be processed. The response displays the status 412 Precondition Failed.
```
412 Precondition Failed
```