diff --git a/docs/.vuepress/config/sidebar-developer.js b/docs/.vuepress/config/sidebar-developer.js index 9425251be8..a61f231dc5 100644 --- a/docs/.vuepress/config/sidebar-developer.js +++ b/docs/.vuepress/config/sidebar-developer.js @@ -242,6 +242,7 @@ const developer = [ ], ] }, + ['/developer-docs/latest/developer-resources/database-apis-reference/rest/relations.html', 'Relations'] ], }, [ diff --git a/docs/developer-docs/latest/developer-resources/database-apis-reference/entity-service/crud.md b/docs/developer-docs/latest/developer-resources/database-apis-reference/entity-service/crud.md index 24199612b0..4e3bcefd5d 100644 --- a/docs/developer-docs/latest/developer-resources/database-apis-reference/entity-service/crud.md +++ b/docs/developer-docs/latest/developer-resources/database-apis-reference/entity-service/crud.md @@ -85,6 +85,8 @@ Syntax: `create(uid: string, parameters: Params)` ⇒ `Entry` | `populate` | Relations, components and dynamic zones to [populate](/developer-docs/latest/developer-resources/database-apis-reference/entity-service/populate.md) | [`PopulateParameter`](/developer-docs/latest/developer-resources/database-apis-reference/entity-service/populate.md) | | `data` | Input data | `Object` | +!!!include(developer-docs/latest/developer-resources/database-apis-reference/snippets/managing-relations.md)!!! + ### Example ```js @@ -105,6 +107,8 @@ Updates one entry and returns it. Syntax: `update(uid: string, id: ID, parameters: Params)` ⇒ `Entry` +!!!include(developer-docs/latest/developer-resources/database-apis-reference/snippets/managing-relations.md)!!! + ### Parameters | Parameter | Description | Type | diff --git a/docs/developer-docs/latest/developer-resources/database-apis-reference/query-engine/single-operations.md b/docs/developer-docs/latest/developer-resources/database-apis-reference/query-engine/single-operations.md index f46944c662..1e5c62f2cc 100644 --- a/docs/developer-docs/latest/developer-resources/database-apis-reference/query-engine/single-operations.md +++ b/docs/developer-docs/latest/developer-resources/database-apis-reference/query-engine/single-operations.md @@ -113,6 +113,8 @@ const entry = await strapi.db.query('api::blog.article').create({ }); ``` +!!!include(developer-docs/latest/developer-resources/database-apis-reference/snippets/managing-relations.md)!!! + ## update() Updates one entry and returns it. @@ -139,6 +141,8 @@ const entry = await strapi.db.query('api::blog.article').update({ }); ``` +!!!include(developer-docs/latest/developer-resources/database-apis-reference/snippets/managing-relations.md)!!! + ## delete() Deletes one entry and returns it. diff --git a/docs/developer-docs/latest/developer-resources/database-apis-reference/rest-api.md b/docs/developer-docs/latest/developer-resources/database-apis-reference/rest-api.md index cc2b831cc9..a586519f2d 100644 --- a/docs/developer-docs/latest/developer-resources/database-apis-reference/rest-api.md +++ b/docs/developer-docs/latest/developer-resources/database-apis-reference/rest-api.md @@ -265,6 +265,10 @@ If the [Internationalization (i18n) plugin](/developer-docs/latest/plugins/i18n. :::: +:::note +While creating an entry, you can define its relations and their order (see [Managing relations through the REST API](/developer-docs/latest/developer-resources/database-apis-reference/rest/relations.md) for more details). +::: + ### Update an entry Partially updates an entry by `id` and returns its value. @@ -304,8 +308,9 @@ Fields that aren't sent in the query are not changed in the database. Send a `nu :::: -:::note -Even with the [Internationalization (i18n) plugin](/developer-docs/latest/plugins/i18n.md) installed, it's currently not possible to [update the locale of an entry](/developer-docs/latest/plugins/i18n.md#updating-an-entry). +:::note NOTES +* Even with the [Internationalization (i18n) plugin](/developer-docs/latest/plugins/i18n.md) installed, it's currently not possible to [update the locale of an entry](/developer-docs/latest/plugins/i18n.md#updating-an-entry). +* While updating an entry, you can define its relations and their order (see [Managing relations through the REST API](/developer-docs/latest/developer-resources/database-apis-reference/rest/relations.md) for more details). ::: ### Delete an entry diff --git a/docs/developer-docs/latest/developer-resources/database-apis-reference/rest/relations.md b/docs/developer-docs/latest/developer-resources/database-apis-reference/rest/relations.md new file mode 100644 index 0000000000..1f5d4c2601 --- /dev/null +++ b/docs/developer-docs/latest/developer-resources/database-apis-reference/rest/relations.md @@ -0,0 +1,346 @@ +--- +title: Managing relations through the REST API +description: Use the REST API to manage the order of relations +canonicalUrl: https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/rest/relations-reordering.html +--- + + + +# 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](/user-docs/latest/content-manager/managing-relational-fields.md#managing-multiple-choices-relational-fields) or through [REST](/developer-docs/latest/developer-resources/database-apis-reference/rest-api.md) 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`](#connect) | Connects new entities.

Can be used in combination with `disconnect`.

Can be used with [positional arguments](#relations-reordering) to define an order for relations. | Partial +| [`disconnect`](#disconnect) | Disconnects entities.

Can be used in combination with `connect`. | Partial +| [`set`](#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](#relations-reordering). + +`connect` can be used in combination with [`disconnect`](#disconnect). + +
+ +:::::: tabs card + +::::: tab Shorthand 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`: + +::: request Example request using the shorthand syntax + +`PUT http://localhost:1337/api/restaurants/1` + +```json +{ + data: { + categories: { + connect: [2, 4], + } + } +} +``` + +::: + +::::: + +::::: tab 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`: + +::: request Example request using the longhand syntax + +`PUT http://localhost:1337/api/restaurants/1` + +```json +{ + 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. + +::: note 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](/developer-docs/latest/developer-resources/database-apis-reference/rest-api.md#requests)). +::: + +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 }`. + +:::note Sequential order +Since `connect` is an array, the order of operations is important as they will be treated sequentially (see combined example below). +::: + +:::caution +The same relation should not be connected more than once, otherwise it would return a Validation error by the API. +::: + +::::: tabs card + +:::: tab Basic example + +Consider the following record in the database: + +```json +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`: + +::: request Example request to update the position of one relation + +`PUT http://localhost:1337/api/restaurants/1` + +```json +{ + data: { + categories: { + connect: [ + { id: 3, position: { before: 2 } }, + ] + } + } +} +``` + +::: +:::: + +:::: tab Combined example + +Consider the following record in the database: + +```json +categories: [ + { id: 1 } + { id: 2 } +] +``` + +Sending the following example in the request body of a PUT request updates multiple relations: + +::: request Example request to reorder several relations + +`PUT http://localhost:1337/api/restaurants/1` + +```json +{ + 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: + +```json +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`](#connect). + +
+ +:::::: tabs card + +::::: tab Shorthand syntax example + +Sending the following request updates the `restaurant` entity with `id` `1`, disconnecting the relations with entities with `id` `2` and `4`: + +::: request Example request using the shorthand syntax + +`PUT http://localhost:1337/api/restaurants/1` + +```json +{ + data: { + categories: { + disconnect: [2, 4], + } + } +} +``` + +::: + +::::: + +::::: tab Longhand syntax example + +Sending the following request updates the `restaurant` entity with `id` `1`, disconnecting the relations with entities with `id` `2` and `4`: + +::: request Example request using the longhand syntax + +`PUT http://localhost:1337/api/restaurants/1` + +```json +{ + 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`](#connect) and [`disconnect`](#disconnect). + +::: note 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](/developer-docs/latest/developer-resources/database-apis-reference/rest-api.md#update-an-entry)) +::: + +:::::: tabs card + +::::: tab Shorthand 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`: + +::: request Example request using the shorthand syntax with set + +`PUT http://localhost:1337/api/restaurants/1` + +```json +{ + data: { + categories: { + set: [2, 4], + } + } +} +``` + +::: + +::::: + +::::: tab 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`: + +::: request Example request using the longhand syntax with set + +`PUT http://localhost:1337/api/restaurants/1` + +```json +{ + data: { + categories: { + set: [ + { id: 2 }, + { id: 4 } + ], + } + } +} +``` + +::: + +::::: +:::::: diff --git a/docs/developer-docs/latest/developer-resources/database-apis-reference/snippets/managing-relations.md b/docs/developer-docs/latest/developer-resources/database-apis-reference/snippets/managing-relations.md new file mode 100644 index 0000000000..d70c86ecb8 --- /dev/null +++ b/docs/developer-docs/latest/developer-resources/database-apis-reference/snippets/managing-relations.md @@ -0,0 +1,3 @@ +:::tip +In the `data` object, relations can be managed with the `connect`, `disconnect`, and `set` parameters using the syntax described for the REST API (see [managing relations](/developer-docs/latest/developer-resources/database-apis-reference/rest/relations.md)). +:::