Expanding references and lists

What this is about

With * you get a reference only as { "id": … }. If you want to see more of the referenced object, you expand the reference: instead of a field name, you put an object into the response.

{ "field": "company", "response": ["companyname", "city"] }

field names the reference, response says which fields of the referenced object you want. This works for single references and for lists.

The example model

employee.company and company.employees are the two sides of the same relation. company is the back reference of employees.

From request to response

flowchart LR
    subgraph R["response"]
        direction TB
        r1["companyname"]
        r2["{ field: employees }"]
        r3["firstname"]
        r4["{ field: department }"]
        r5["name"]
        r2 --> r3
        r2 --> r4
        r4 --> r5
    end
    subgraph A["Response"]
        direction TB
        a1["company<br/>companyname: Codamic AG"]
        a2["employees[0]<br/>firstname: Daniel"]
        a3["department<br/>name: Development"]
        a4["employees[1]<br/>firstname: Anna"]
        a5["department<br/>name: Sales"]
        a1 --> a2
        a1 --> a4
        a2 --> a3
        a4 --> a5
    end
    R ==> A

POST /api/rest/hr/company/read/a1…
{
  "response": [
    "companyname",
    {
      "field": "employees",
      "response": [
        "firstname",
        { "field": "department", "response": ["name"] }
      ]
    }
  ]
}

{
  "data": {
    "id": "a1…",
    "companyname": "Codamic AG",
    "employees": [
      { "id": "7f3…", "firstname": "Daniel",
        "department": { "id": "d4…", "name": "Development" } },
      { "id": "8b1…", "firstname": "Anna",
        "department": { "id": "d7…", "name": "Sales" } }
    ]
  },
  "meta": { "error": false }
}

The response is shortened: fields you did not request are actually in it as null, and every object has its system fields _createdOn and _updatedOn.

Single reference and list work differently

A list with its own filter

POST /api/rest/hr/company/read/a1…
{
  "response": [
    "companyname",
    {
      "field": "employees",
      "response": ["firstname", "lastname"],
      "parameter": {
        "limit": 5,
        "order": [{ "field": "_createdOn", "order": "DESC" }],
        "query": {
          "type": "AND",
          "filter": [{ "key": "lastname", "value": "M%", "param": "LIKE" }]
        }
      }
    }
  ]
}

{
  "data": {
    "id": "a1…",
    "companyname": "Codamic AG",
    "employees": [
      { "id": "7f3…", "firstname": "Daniel", "lastname": "Mertins" },
      { "id": "2c9…", "firstname": "Eva", "lastname": "Meier" }
    ]
  },
  "meta": { "error": false }
}

What CDMS turns this into as a search on employee:

flowchart TB
    subgraph W["WHERE for employee"]
        direction TB
        w1["company.id = 'a1…'<br/>(added by CDMS)"]
        w2["AND lastname LIKE 'M%'<br/>(your filter)"]
        w3["AND row filters of employee<br/>(own data, attribute filters)"]
    end
    W --> O["ORDER BY _createdOn DESC"]
    O --> L["at most 5"]

How filtering, sorting and paging work in detail is described in the search chapter, among others under Filters in nested lists and Paging and match count.

In a search: one sub-query per match

If you expand a list in a search, CDMS runs the sub-query for each match separately:

sequenceDiagram
    participant C as Client
    participant D as CDMS
    participant DB as Database
    C->>D: POST /hr/company/query (limit 25) with { field: employees }
    D->>DB: search on company
    DB-->>D: 25 companies
    loop for each of the 25 companies
        D->>DB: search on employee with company.id = …
        DB-->>D: employees of this company
    end
    D-->>C: 25 companies, each with its list employees

With 25 companies these are 25 additional searches. If every company has 500 employees and you set no limit, 12,500 employees come back. More on this under What happens in the database when reading.

What a nested list does not have

If you need the total number of entries of a list, ask the child model directly: POST /hr/employee/query with the filter company.id = … returns meta.totalCount.

Decision table

Instead of the read role of the target model, a role on the relation itself can be enough. See Permissions on relations. The table describes the default, strict mode.

Pitfalls

Where to go next

• If the reference points to an abstract model: Reading through abstract types
• What this means for the database: What happens in the database when reading