Create and read back: STRICT or LENIENT

What this is about

A create does not just answer “ok”, but with the created object, the way you requested it in response. To do that, CDMS reads the object back after saving it, with your permissions and filters, exactly like a normal read.

This read-back can fail even though the create succeeded. For example:

• You lack the read role of the model. You may create, but not read.
• The new object is filtered out by your row filters. For example, you create an order for a company that your attribute filter does not show you.
• A READ hook throws an error while reading.

What happens then is decided by the CreateReadMode: STRICT or LENIENT.

The two modes

If reading back succeeds, both modes behave the same: 200 with the object.

The response with LENIENT

POST /api/rest/order/create
{
  "data": { "orderNr": "A-1000", "companyId": "123456" },
  "response": ["id", "orderNr"],
  "createReadMode": "LENIENT"
}

{
  "error": "CreateSucceededReadFailedException",
  "messageKey": "CDMS_CREATE_SUCCEEDED_READ_FAILED",
  "code": "200",
  "layer": "system",
  "id": "5a2b…"
}

The response has status 200, but the shape of an error response: no data, instead error, messageKey and id. So for a create, do not check only the status, but also whether data is there. See The response format: data and meta.

Choosing the mode

• Per request: "createReadMode": "LENIENT" in the body, next to data and response. This applies to POST /create, /create/upload and creating through the hub API of an abstract model.
• For the whole installation: the setting codamai.cdms.api.create-read-mode in the application’s configuration, default STRICT.
• Singletons always read back in STRICT mode when created.

For PUT, PATCH and rollback there is no choice: there, writing and reading back always belong to one transaction.

When which mode fits

Pitfalls

What comes next

• The bracket around a request: One request, one transaction
• How a request creates: Creating an object
• The shape of responses: The response format: data and meta