Managing relations through the REST API
Defining relations between content-types (that are designated as entities in the database layers) is connecting entities with each other.
Relations between content-types can be managed through the admin panel or through REST requests sent to the Content API.
Relations can be connected, disconnected or set through the Content API by passing parameters in the body of the request:
| Parameter name | Description | Type of update |
|---|---|---|
connect | Connects new entities. Can be used in combination with disconnect.Can be used with positional arguments to define an order for relations. | Partial |
disconnect | Disconnects entities. Can be used in combination with connect. | Partial |
set | Set entities to a specific set. Using set will overwrite all existing connections to other entities.Cannot be used in combination with connect or disconnect. | Full |
connect
Using connect in the body of a request performs a partial update, connecting the specified relations.
connect accepts either a shorthand or a longhand syntax. In the following examples, numbers refers to entity ids:
| Syntax type | Syntax example |
|---|---|
| shorthand | connect: [2, 4] |
| longhand | connect: [{ id: 2 }, { id: 4 }] |
You can also use the longhand syntax to reorder relations.
connect can be used in combination with disconnect.
connect can not be used for media attributes (see Upload plugin documentation for more details).
- Shorthand syntax example
- Longhand syntax example
Sending the following request updates the restaurant entity with id 1, using the categories attribute to connect the entity with entities with id 2 and 4:
PUT http://localhost:1337/api/restaurants/1
{
data: {
categories: {
connect: [2, 4]
}
}
}
const fetch = require('node-fetch');
const response = await fetch(
'http://localhost:1337/api/restaurants/1',
{
method: 'put',
body: {
data: {
categories: {
connect: [2, 4]
}
}
}
}
);
Sending the following request updates the restaurant entity with id 1, using the categories attribute to connect the entity with entities with id 2 and 4:
PUT http://localhost:1337/api/restaurants/1
{
data: {
categories: {
connect: [
{ id: 2 },
{ id: 4 }
]
}
}
}
const fetch = require('node-fetch');
const response = await fetch(
'http://localhost:1337/api/restaurants/1',
{
method: 'put',
body: {
data: {
categories: {
connect: [
{ id: 2 },
{ id: 4 }
]
}
}
}
}
);
Relations reordering
Positional arguments can be passed to the longhand syntax of connect to define the order of relations.
The longhand syntax accepts an array of objects, each object containing the id of the entry to be connected and an optional position object to define where to connect the relation.
The syntaxes described in this documentation are useful for one-to-many, many-to-many and many-ways relations.
For one-to-one, many-to-one and one-way relations, the syntaxes are also supported but only the last relation will be used, so it's preferable to use a shorter format (e.g.: { data: { category: 2 } }, see REST API documentation).
To define the position for a relation, pass one of the following 4 different positional attributes:
| Parameter name and syntax | Description | Type |
|---|---|---|
before: id | Positions the relation before the given id. | Entry id |
after: id | Positions the relation after the given id. | Entry id |
start: true | Positions the relation at the start of the existing list of relations. | Boolean |
end: true | Positions the relation at the end of the existing list of relations. | Boolean |
The position argument is optional and defaults to position: { end: true }.
Since connect is an array, the order of operations is important as they will be treated sequentially (see combined example below).
The same relation should not be connected more than once, otherwise it would return a Validation error by the API.
- Basic example
- Combined example
Consider the following record in the database:
categories: [
{ id: 1 }
{ id: 2 }
]
Sending the following request updates the restaurant entity with id 1, connecting a relation of entity with id 3 for the categories attribute and positioning it before the entity with id 2:
PUT http://localhost:1337/api/restaurants/1
{
data: {
categories: {
connect: [
{ id: 3, position: { before: 2 } },
]
}
}
}
Consider the following record in the database:
categories: [
{ id: 1 }
{ id: 2 }
]
Sending the following example in the request body of a PUT request updates multiple relations:
PUT http://localhost:1337/api/restaurants/1
{
data: {
categories: {
connect: [
{ id: 6, position: { after: 1} },
{ id: 7, position: { before: 2 } },
{ id: 8, position: { end: true } },
{ id: 9 },
{ id: 10, position: { start: true } },
]
}
}
}
Omitting the position argument (as in id: 9) defaults to position: { end: true }. All other relations are positioned relative to another existing id (using after or before) or relative to the list of relations (using start or end). Operations are treated sequentially in the order defined in the connect array, so the resulting database record will be the following:
categories: [
{ id: 10 },
{ id: 1 },
{ id: 6 },
{ id: 7 },
{ id: 2 },
{ id: 8 },
{ id: 9 }
]
disconnect
Using disconnect in the body of a request performs a partial update, disconnecting the specified relations.
disconnect accepts either a shorthand or a longhand syntax. In the following examples, numbers refers to entity ids:
| Syntax type | Syntax example |
|---|---|
| shorthand | disconnect: [2, 4] |
| longhand | disconnect: [{ id: 2 }, { id: 4 }] |
disconnect can be used in combination with connect.
- Shorthand syntax example
- Longhand syntax example
Sending the following request updates the restaurant entity with id 1, disconnecting the relations with entities with id 2 and 4:
PUT http://localhost:1337/api/restaurants/1
{
data: {
categories: {
disconnect: [2, 4],
}
}
}
Sending the following request updates the restaurant entity with id 1, disconnecting the relations with entities with id 2 and 4:
PUT http://localhost:1337/api/restaurants/1
{
data: {
categories: {
disconnect: [
{ id: 2 },
{ id: 4 }
],
}
}
}
set
Using set performs a full update, replacing all existing relations with the ones specified, in the order specified.
set accepts a shorthand or a longhand syntax. In the following examples, numbers refers to entity ids:
| Syntax type | Syntax example |
|---|---|
| shorthand | set: [2, 4] |
| longhand | set: [{ id: 2 }, { id: 4 }] |
As set replaces all existing relations, it should not be used in combination with other parameters. To perform a partial update, use connect and disconnect.
Omitting any parameter is equivalent to using set.
For instance, the following 3 syntaxes are all equivalent:
data: { categories: { set: [{ id: 2 }, { id: 4 }] }}data: { categories: { set: [2, 4] }}data: { categories: [2, 4] }(as used in the REST API documentation)
- Shorthand syntax example
- Longhand syntax example
Sending the following request updates the restaurant entity with id 1, replacing all previously existing relations and using the categories attribute to connect the entity with entities with id 2 and 4:
PUT http://localhost:1337/api/restaurants/1
{
data: {
categories: {
set: [2, 4],
}
}
}
Sending the following request updates the restaurant entity with id 1, replacing all previously existing relations and using the categories attribute to connect the entity with entities with id 2 and 4:
PUT http://localhost:1337/api/restaurants/1
{
data: {
categories: {
set: [
{ id: 2 },
{ id: 4 }
],
}
}
}