Managing relations through the REST API Beta

Relations between content-types can be managed through the admin panel or through REST requests sent to the Content API.

Relations can be added, updated, or removed through the Content API by passing parameters in the body of the request:

Parameter name	Description	Type of update
connect	Adds relation(s). Can be used in combination with disconnect. Can be used with positional arguments to define an order for relations.	Partial
disconnect	Removes relation(s). Can be used in combination with connect.	Partial
set	Sets relations, replacing all the existing ones. Must be used alone.	Full

Using connect allows adding positional arguments to define an order for relations.

connect

Using connect in the body of a request performs a partial update, adding specified relations.

connect accepts either a shorthand or a longhand syntax.

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.

Example request using the shorthand syntax

PUT http://localhost:1337/api/restaurants/1

{
  data: {
    categories: { 
      connect: [2, 4],
    }
  }
}

Example request using the longhand syntax

PUT http://localhost:1337/api/restaurants/1

{
  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 relation to be connected and an optional position object to define where to connect the relation.

✏️ Different syntaxes for different relations

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 }.

✏️ Sequential order

Since connect is an array, the order of operations is important as they will be treated sequentially (see combined example below).

Consider the following record in the database:

categories: [
  { id: 1, order: 1 }
  { id: 2, order: 2 }
]

Sending the following request updates a restaurant entry and creates a third relation of id 3 for the categories attribute and position it before the relation with id 2:

Example request to update the position of one relation

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, order: 1 }
  { id: 2, order: 2 }
]

Sending the following example in the request body of a PUT request updates multiple relations:

Example request to reorder several 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 defaults (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, order: 1 },
  { id: 1, order: 2 },
  { id: 6, order: 3 },
  { id: 7, order: 4 },
  { id: 2, order: 5 },
  { id: 8, order: 6 },
  { id: 9, order: 7 }
]

disconnect

Using disconnect in the body of a request performs a partial update, removing specified relations.

disconnect accepts either a shorthand or a longhand syntax.

Syntax type	Syntax example
shorthand	disconnect: [2, 4]
longhand	disconnect: [ {id: 2}, {id: 4} ]

disconnect can be used in combination with connect.

Example request using the shorthand syntax

PUT http://localhost:1337/api/restaurants/1

{
  data: {
    categories: { 
      disconnect: [2, 4],
    }
  }
}

Example request using the longhand syntax

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.

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 set

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)

Example request using the shorthand syntax with set

PUT http://localhost:1337/api/restaurants/1

{
  data: {
    categories: { 
      set: [2, 4],
    }
  }
}

Example request using the longhand syntax with set

PUT http://localhost:1337/api/restaurants/1

{
  data: {
    categories: { 
      set: [
        { id: 2 },
        { id: 4 }
      ], 
    }
  }
}