POST request
A POST request is used to partially update existing instances at location addressed by passing appropriate data in a body. In contrast to PUT or PATCH, post allows inserting/updating multiple instances passed in a JSON array in body. Before inserting or updating instances, POST tries to locate instances by means of key attributes passed in body objects.
location -is the property source which must address a collection property (see Symbol reference / location - HTTP URL). Since data for locating instances is passed in body, addressing an instance or elementary property in location will cause an error.
body - is a single JSON object or array (of objects) which contain name/values pairs for key component attributes and properties to be updated (see body definition in Symbol reference / body - request data for HTTP requests). Properties passed in body must refer to attributes, MEMO or BLOB properties.
noreplace - In case of passing the noreplace parameter, an instance that already exists, will not be updated.
noinsert - In order to avoid creating new instances, noinsert may be passed instead.
Since POST first tries to locate an instance by main key attribute values passed in the object, POST does not allow changing main key attribute values. In order to update main key attribute values, one should use PATCH.
When creating or updating instances conflicts with parameter passed, the request terminates with an error and no changes are made.
Properties of an existing instance not referenced in the body remain unchanged. Passing null for a property will reset the property value to its initial state.
When terminating normally, POSTreturns following response:
- updated - when data has been updated successfully
- created -when a new instance has been created
When creating new instances, unique key component values for each instance have to precede all other attributes and references in the JSON instance (part between { ... } ).
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.