Cycle protection

What this is about

Relations point in both directions: the company knows its employees, and each employee knows their company. If a program blindly follows all relations, it goes around in circles: company → employee → company → employee … This is called a cycle.

flowchart LR
    A["Company"] -->|employees| B["Employee"]
    B -->|company| A
    B -.->|"CDMS stops here"| X(("■"))

When reading: the response is the limit

CDMS only follows a relation if you expand it in the response. You have to write out each level yourself. Because your response is finite, so is the answer.

POST /api/rest/group/read/a1…
{
  "response": ["name",
    { "field": "children", "response": ["name",
      { "field": "parent", "response": ["name",
        { "field": "children", "response": ["name"] }
      ] }
    ] }
  ]
}

{
  "data": {
    "name": "A",
    "children": [
      { "name": "B",
        "parent": {
          "name": "A",
          "children": [ { "name": "B", "children": null, "parent": null } ]
        }
      }
    ]
  },
  "meta": { "error": false }
}

As you can see, A and B appear more than once. CDMS does not merge them. It returns each level the way you asked for it. On the last level, children and parent are null, because you did not ask for them there.

More about expanding in Expanding references and lists.

When writing: back reference and each object once

With nested writing, CDMS could also go around in circles: the company writes its employees, and each employee has a field company that points back to the company. Two rules prevent this:

1. The back reference is not followed. From a child, CDMS does not go back to the parent object. It sets the link from above. If the child still contains a back reference, the parent object wins. See Both sides of a relation.
2. Each object of the request is processed only once. For this, CDMS internally marks which objects it has already handled. The mark is stored in the internal field _reference.

The field _reference

_reference is an internal marker that CDMS uses only while it processes a request. In read responses, it appears as "_reference": null.

The marker belongs to the server. If you send a read object back, the _reference in it does no harm — CDMS does not accept it. Only what CDMS sets itself while processing counts.

Pitfalls

Where to go next

• Reading references: Expanding references and lists
• The other side when writing: Both sides of a relation
• System fields: System fields that the server sets