HTTP API PATCH

PATCH Basics

The PATCH verb is used to update existing resources. The PATCH method is called on the singular resource. When no sub resources or dynamic records are involved, PATCH and PUT are identical.

To update an existing "title" resource, one can PATCH the following resource representation to "[api-context-root]/generic/titles/{id}":

{
  "displayCode": "Msc 2",
  "objectVersionNumber": <object version number>

}

The response body contains a representation of the updated resource in the default representation as described in section Default Resource Representation (GET):

{
  "id": ,
  "active": "Y",
  "code": "MYCODE",
  "displayCode": "My Code",
  "displayOrder": 1,
  "displayPosition": "A",
  "objectVersionNumber": ,
  "links": [
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/titles/",
      "rel": "self",
    }
  ]
}

The resource representation sent to HTTP API for a PATCH method must include:

  1. The "objectVersionNumber" property as returned by a previous HTTP API GET operation if HTTP API should enforce concurrency control. If this is not included then the request still goes successfully but can overwrite another change done in parallel.

  2. The properties to be changed with their new values.

Include Sub Resources

When sub resources are involved, PUT and PATCH behave differently:

  1. With PUT, clients must send in all sub resources, for example all claim lines of a claim. The list of sub resources present in the payload, is the truth. The sub resources that are not included, are removed.

  2. With PATCH, clients have to send only the sub resources they want to operate on. The sub resources that are not included in the payload, are not impacted.

The following example shows a payload that updates a claim with and a single claim line (other claim lines are not impacted):

{
  "objectVersionNumber": <claim object version number>
    "claimDate" : "2010-04-30",
    ... ... .... ... ... ...
    "claimLines" : [ {
        "op": "replace"
        "id": <claimline id>,
        "objectVersionNumber": <claimline object version number>,
        "subscriptionDate": "2009-07-01",
        ... ... .... ... ... ...
       ]
     }
}

The "op" keyword defines the operation, in this case "replace".

The resource representation for each sub resource must include:

  1. The "id" property as returned by a previous HTTP API GET operation.

  2. The "objectVersionNumber" property as returned by a previous HTTP API GET operation.

    Note

    If the claimLineList is not included at all, the existing claim lines are not modified or deleted.

Include Dynamic Records

For dynamic records in a PATCH operation, the same applies: clients have to send only the sub resources they want to operate on. The sub resources that are not included in the payload, are not impacted. The example below adds a new record to the existing ones.

{
  "objectVersionNumber": <object version number>
    "id" : ,
    ... ... .... ... ... ...
    "myDentists": [{
      "op": "add"
      "id": 123,
      "dentist": {
        "flexCodeDefinitionCode": "<code of the flex code definition>",
        "value": "<flex code>"
      },
      "lastVisit": "2012-05-11"
    }]
}

Discover Properties

See the "Discover Properties" section in HTTP API PUT.The exact same techniques can be used for the PATCH payload.

PATCH Processing Details

  1. HTTP API is forgiving: when an unknown construct is present in the resource representation, it is ignored. No error is given. This applies to:

    • 1. Unknown properties.

    • 2. Properties that do exists, but cannot be set by a client.

    • 3. Unknown sub resources.

    • 4. Unknown dynamic fields and unknown dynamic records.

  2. HTTP does validate values however for all known constructs. As soon as a property or sub resource if recognized, it’s value is fully validated.

  3. When any validation fails, the whole message is discarded. An error resource is returned as described in the section Operations Overview and Concepts. An HTTP error status code is returned, as described in the section Response Messages

  4. When all validations pass, the resource is created.

    • 1. The top level resource is updated with the new values from the payload

    • 2. The operation on the sub resource is performed based on the value of the "op" property:

      • 1.If "op" = "add", the sub resource is added.

      • 2.If "op" = "remove", the sub resource is removed. The sub resource is found using the value of the "id".

      • 3.If "op" = "replace", the sub resource is updated with the new values. The sub resource is found using the value of the "id". Properties that are not present in the payload are not impacted

  5. The updated resource is returned together with HTTP status code 200.

Combined Example

The HTTP PATCH can be used to do several operations in one go. Consider the following example:

  • update claim

    • claimDate

  • update claim line 1

    • familyCode

    • manualBenefits

  • delete existing claim line 2

  • create new claim line 3

These changes are reflected in the following resource representation:

{
  "objectVersionNumber": <object version number>
    "id" : "7",
    "claimDate : "2010-04-30",
    "claimLines" : [ {
        "id": 10,
        "op":"replace",
        "objectVersionNumber": <object version number>
        "familyCode": "SCOT",
        "keepBenefits": "N",
     },
     {
       "id": 11,
       "objectVersionNumber": <object version number>
       "op":"remove"
     },
     {
        "op": "add"
        "familyCode": "SCOT",
        "keepBenefits": "Y",
        ... ... ... ... ... ... ...
        // rest of the required details for the new claim line
     }
   ]
}

For this payload, the PATCH method leads to the the following operations:

  • update claim.claimDate

  • update claimLine1.familyCode, claimLine1.manualBenefits

  • delete an existing claimLine2

  • insert a claimLine3

Functional Key based PATCH

A functional key based PATCH operation uses the functional key to identify the resource, instead of the internal id:

  • To update an existing "title" resource using the internal id, use URI "[api-context-root]/generic/titles/{id}"

  • To update an existing "title" resource using the functional key, use ARI "[api-context-root]/generic/titles/key/{code}"

When using a functional key based PATCH, there is no need to know internal id’s. This is most useful in integration scenario’s (machine-machine communication). A functional key based PATCH uses the same request/response payload representation as the id based PATCH operation.

Warning

Functional key based PATCH is only supported on resources that have a "code" property. Exception: Policy: It is identified by code and version uniquely. If Functional key based PATCH is used for policy resource, the method is applied to the latest version of policy with that code.

Include Sub Resources

Sub resources can be included in the PATCH payload. A sub resource can have its own functional key. For example, a "policy" PATCH payload can include "subresources policybrokeragents". Subresources can as well be matched using the functional key (in addition to id based matching). Subresources can have a functional key of a single field, but multiple fields are also possible. The composition of the functional key can be retrieved from the metadata. Snippet from the "policybrokeragents/definition" resource:

...
"x-oi-composite-functional-key": [
 "agent",
 "broker",
 "startDate",
 "policy"
 ],
 "x-oi-definition-name": "PolicyBrokerAgent"

The four properties "agent", "broker", "startDate" and "policy" identify a policybrokeragent sub resource. In a patch payload, the "policy" property is implicit, because the subresource is contained inside a "policy" resource. So for a functional patch operation on the subresource "policybrokeragent", at least "agent", "broker", "startDate" must be sent in, together with the other changes to be made.

Example payload to end a single policy broker agent for a policy:

{
   "policyBrokerAgentList": [
      {
         "op": "replace",
         "startDate": "2016-01-01",
         "agent"  :
         {
           "code": "PO0033_AGEN_001"
         },
         "broker"  :
         {
           "code": "PO0033_BROK_001"
         },
         "endDate"  : "2016-01-31"
      }
   ]
}

The properties "startDate", "agent" and "broker" are used to locate the policy broker agent of the policy to be replaced. The other properties in the payload (only "endDate" in this example) are used to update the record.

Include Multi Value Dynamic Fields

Multi value dynamic fields are ignored.

Include Dynamic Records

Dynamic records are ignored.