Updating an Existing Resource

Existing resources can be updated using the HTTP PATCH (or HTTP MERGE) method.

Example: Update a Service Request

PATCH http://myserver:5181/odata/ServiceRequests(139239)  HTTP/1.1
Content-Length: 48
Content-Type: application/json


{
    "Solution": "Cleaned the printer and replaced part-no LP32893.",
    "ActualStart": "2001-07-16T12:00:00",
    "ActualDuration":"PT1H",
    "ActualCost":"12.54",
    "Priority": {
        "Text": "None"
    },
    "Status": {
        "Value": 3120234513,
        "Text": "Waiting"
    },
    "Impact": {
        "Value": 3094610021
    },
    "ServicecallCode3": {
        "@odata.type": "#PROLIN.Web.OData.Model.Code",
        "Value": 3094610021
    }
}
  • Date/time values are assumed to be in UTC.
  • Set a text, numeric, date/time or duration property to null to clear its value. To clear a reference, see Removing a Relationship.
  • Codes can be assigned using their id value, localized text, or both.
  • Custom codes require the @odata.type annotation.

Editing Entity References

Entity references (including custom references) can be updated using @odata.bind:

{
  "Description": "Printer is not working properly.",
  "Information": "The printer in room 14C is causing paperjams all the time.",
  "Status": {
    "Text": "Waiting",
    "Value": 3120234513
  },
  "Caller@odata.bind": "/Persons(234)",
  "ScPerson1@odata.bind": "/Persons(234)"
}

Applying a Template

A template can be applied to an existing entity by binding it, as when creating an entity from a template:

PATCH http://myserver:5181/odata/ServiceRequests(281697119437098)  HTTP/1.1
Content-Type: application/json

{
  "Template@odata.bind": "/Templates(3101753354)",
  "Information": "Reclassified as a printer request."
}

This works as Apply template in the Smart Client: the template’s values replace the entity’s current values, and approval data is cleared. Values sent in the same request are applied after the template and override its values. Binding the template the entity has already does not apply it again. The template must belong to the same entity type, and the entity must still be valid once the template’s values are applied; otherwise the request fails with 400 Bad Request.

Values That Cannot Be Stored

A PATCH or POST stores every property value it specifies, or fails and stores nothing, as OData 4.0 requires:

The request sets a property that Response
the role of the user may not modify 403 Forbidden
is read-only, such as ID or the dates in Registration 400 Bad Request
the server does not store, such as a property the resource does not have or a custom field that is not activated 400 Bad Request
is refused when it is set, for example a custom field that is not enabled for the item’s category, or an invalid value 400 Bad Request

The error message names each property and the reason. When the role of the user may not modify one of the properties, the response is 403 Forbidden and names only those. A failed request changes nothing, also not the relationships it contains.

A PATCH that sends a property with the value it already has does not change it, so sending back ID or Registration as they were read succeeds. The key Uid is ignored.

Additional Notes

  • Duration and date/time formats follow ISO 8601.
    More details: ISO 8601 on Wikipedia

  • When performing a PATCH operation, you can include a Prefer header to request that the updated object be returned.

Back to top