PUT request

A PUT request is used to create new or update existing instances addressed in location by passing appropriate data in a body. The PUT request body contains data to be stored.

When an instance already exists at required location, properties of the existing instance referenced in body will be updated, when replace is passed as parameter. Properties of an existing instance not referenced in the body are reset to their initial state. In order to prevent single properties in existing instances from being reset, one should use PATCH rather than PUT.

In case of a collection source (no locator passed), a new instance is inserted/appended to the collection when the collection is unordered or ordered by __AUTOIDENT (auto-number). Otherwise, collection sources will cause an error.

location - is the property source which should address a single (not existing) instance (see Symbol reference / location - HTTP URL). Since PUT is creating a new instance, the source property for PUT must not be an elementary source property. Usually, the source property in the PUT location refers to a non existing instance. PUT first tries to insert the new instance referenced in location before updating properties with data passed in body.

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

replace - In case of passing the replace parameter, an instance that already exists will be updated. Otherwise, the request terminates with an error message.

When terminating normally, PUTreturns following response:

• created -when a new instance has been created
• updated - when data has been replaced

The identifying key value for new instances should be passed in the PUT 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.