HTTP API PUT

PUT Basics

The PUT verb is used to update existing resources. The PUT method is called on the singular resource.

To update an existing "title" resource, one can PUT 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 PUT method should include:

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.
The properties to be changed with their new values.

Include Sub Resources

PUT can also be used to update sub resources. The top level resource and all the included resources are persisted in one transaction using PUT.

The following example shows a payload that updates a claim with a single claim line:

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

The resource representation for each sub resource must include:

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

The resource representation sent in with PUT represents the new truth. So in the example above, if the claimLineList includes only a single claimline, and the claim used to have more claim lines before, the other claim lines are removed.

Note: Matching the incoming sub resource presentation to existing resources is done using the "id" property.
Note: If the claimLineList is not included at all, the existing claim lines are not modified or deleted.

Discover Properties

Using Metadata

Which properties can be included in a PUT payload can be discovered from the its metadata. For example,

http://<host>:<port>/[api-context-root]/generic/messagegroups/metadata.

Using the edit-form Link

As an alternative to using the metadata, HTTP API can also generate a resource representation as a starting point for the PUT operation. Clients can request that resource, fill in the values they want to change and PUT it to the singular resource.

The root resource of all HTTP API resources includes a link of type "edit-form":

{
    "name": "<resource>",
    "links": [
        {
            "rel": "canonical",
            "href": "http://<host>:<port>/[api-context-root]/generic/<resource>"
        },
...
        {
            "rel": "edit-form",
            "href": "http://<host>:<port>/[api-context-root]/generic/<resource>/edit-form"
        },
    ]
}

The "edit-form" link is only present for resources that support PUT or PATCH.

Note

The "edit-form" link is not dependent on the access rights of the current user.

The "edit-form" resource returns a representation with all properties that HTTP API will process when present in the PUT or PATCH method. For example, technical properties that are derived on the server, are not present in the "edit-form" resource because HTTP API ignores. See Operations Overview and Concepts which properties HTTP API will and will not process.
The properties are filled with empty values. Clients have to fill the values for properties they want to change, and remove the other properties from the payload before sending it.
The properties are returned in their "native" format. This means, a client just can fill in the values to be changed and send the payload to HTTP API without the need to make structural changes in the format. The "native" format of each type is documented in Property Representation (GET).
Sub resources are not expanded by default. They can be included using "expand", see Influence Resource Representation
For linked resources by default the "id" property is used. This cannot be influenced using "fields".

What to Include

As said in section Property Representation and Handling (PUT, POST, PATCH), clients need not supply values for all properties, they may send in incomplete resource representations.

PUT Processing Details

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.
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
When all validations pass, the resource is updated:
- 1. The top level resource is updated with the new values from the payload
- 2. Sub resources are matched on the "id" property
  - 1. If no matching sub resource found, a new sub resource is created
  - 2. If a matching sub resource found, the sub resource is updated
  - 3. All other sub resource are removed.
The updated resource is returned together with HTTP status code 200.