Who this is for. The integrations engineer writing records, and anyone who sends back a record they have just read. When a payload sets a relation, both forms below move page 1885 under page 72:
Unit 01 · The REST API
A relation as an id or an object
A payload can set a relation with a bare id or with an object carrying one, and both do the same thing. What the neighbouring forms do, which is not the same thing at all: an object with more fields edits the related record, and one without an id creates a new one.
HTTP
PUT /cdna-api/pages/page/1885
{"parent": 72}
HTTP
PUT /cdna-api/pages/page/1885
{"parent": {"id": 72}}Integrators often assume only one works; both do, and a client that builds payloads from records it has just read can send the object form back untouched. The object form has neighbours that look similar and are not:
| You send | The platform |
|---|---|
72 or {"id": 72} | Points the relation at record 72 |
{"id": 72, "name": "Guides"} | Points the relation at record 72 and edits record 72, setting its name |
{"name": "Guides"} | Creates a new related record and points the relation at it |
null | Clears the relation |
0 | Usually refused with a 422, “Could not find the referenced record with id 0”. On a page's parent it is read as no parent, which a page with a slug then fails validation for. Never send 0 to mean “none”: send null |
[3, 4] or [{"id": 3}, {"id": 4}] on a to-many relation | Replaces the whole set with records 3 and 4. It does not add to what is there |
Sending back what you read
A record read with a nested selector carries its relations as objects with several fields. Send that object back as it is and you also send those fields, and the related record is edited with whatever values you happened to read, perhaps stale ones. Strip a read-back object down to its id before sending it as a relation, unless editing the related record is what you mean.
- A list must be all ids or all objects; mixing the two is refused.
- To add one item to a to-many relation, read the current set, add the id, and send the whole set back. Two clients doing this at once will lose one addition, so keep such writes in one process.
- Leave a relation out of the payload to leave it unchanged. Omitted is not the same as
null.
The fields a relation's record accepts are on its model in the generated Reference. Layout areas and custom fields that point at records (an image area, a record field) take ids the same way; Writing areas and Custom fields give the shape for each.
Go deeper
Was this page helpful?
Your answer goes to the docs team.