Field selection with response

What this is about

Every request that returns data carries a response list. It tells CDMS which fields should be in the response. This applies to read, query, create, update, patch and rollback.

{
  "response": ["id", "firstname", "+", { "field": "company", "response": ["companyname"] }],
  "exclude": ["internalNote"]
}

The three kinds of entries

An entry in response is either a text or an object:

flowchart TB
    E["Entry in response"] --> T{"Text or object?"}
    T -->|"Text without + and *"| F["Field name<br/>exactly this simple field"]
    T -->|"Text with + or *"| W["Wildcard<br/>many fields at once"]
    T -->|"Object { field, response }"| O["Expand a reference<br/>with its own field selection"]

Next to response there is also the exclude list. It removes fields again that a wildcard added.

The object in detail

An object expands a reference. It has up to four keys:

Because response inside the object may contain objects again, you can nest as deep as you like. How that works is described under Expanding references and lists.

Example on the employee model

The same model as on the other pages of this chapter: employee with firstname, lastname and the references company and department.

POST /api/rest/hr/employee/read/7f3…
{
  "response": [
    "firstname",
    "+name",
    { "field": "company", "response": ["companyname"] }
  ]
}

{
  "data": {
    "id": "7f3…",
    "firstname": "Daniel",
    "lastname": "Mertins",
    "company": { "id": "a1…", "companyname": "Codamic AG" },
    "department": null
  },
  "meta": { "error": false }
}

firstname appears twice, once as a name and once through +name. That does no harm, CDMS reads every field only once.

What CDMS does with unusual entries

Decision table

Permissions: per model and per relation

CDMS decides whether you may read something per model and per relation. Whoever may read employee may read the simple fields of employee, unless a field carries a read role of its own: then + leaves it out without this role, and requesting it by name results in 403. See Protected values. A role only comes into play when the response reaches into another model: then you need its read role or a role on the relation itself. See Model roles and Permissions on relations.

The tables above describe the default, strict mode. Without it, a single reference without the role is silently null; the other cases still fail, only with a different status or key. See Strict mode.

Pitfalls