PATCH request

A PATCH request is used to partially update an existing instance addressed in location by passing appropriate data in a body. The PATCH request body contains data to be stored. When no instance exists at required location, a new instance is created, when insert has been passed as parameter. Otherwise, the request returns an error.

location - is the property source (see Symbol reference / location - HTTP URL), which must address a single instance or an elementary property (attribute, MEMO or BLOB). Since PATCH is, usually, updating existing instances, location must refer to an existing instance. PATCH first tries to locate the instance referenced in location before updating properties with data passed in body.

body - is a JSON object or value, which contains a value or name/values pairs for properties to be updated and data to be stored (see body definition in Symbol reference / body - request data for HTTP requests). Properties passed in body must refer to attributes, MEMO or BLOB properties.

insert - when passing the parameter insert (update or insert), instances are created when not yet existing. When not being passed and no instance exists at required location, the request fails.

When location refers to an elementary property, the data (value) passed in body is stored to the property. When location refers to an array attribute, body should contain a value array and values are stored according to position in the array. Attribute elements not referenced in the value array (less values than attribute elements) remain unchanged. Passing too many values will cause an error.

When location refers to an object instance, the data passed in body must be an object containing name/values pairs. Names must refer to property names defined for the object. Properties not referenced remain unchanged. Passing null as value will reset the property value to its initial state. Undefined property names will cause an error.

When terminating normally, PATCHreturns following response:

• updated - when data has been updated successfully
• created -when a new instance has been created (insert passed)

The identifying key value for instances to be created should be passed in the PATCH location (part of URL). When passing unique key component values in the body, those should precede all other attributes and references.

An error description is returned as JSON object (see Error handling) in case of key conflicts or other error(s) in the request definition and no changes are made.