From bd606a59f8f66ad4b522c7b0de81fb2f3a48844f Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Wed, 7 Dec 2022 19:56:50 +0100 Subject: [PATCH 01/38] Add relations management through REST API --- docs/.vuepress/config/sidebar-developer.js | 1 + .../database-apis-reference/rest-api.md | 9 +- .../database-apis-reference/rest/relations.md | 229 ++++++++++++++++++ 3 files changed, 237 insertions(+), 2 deletions(-) create mode 100644 docs/developer-docs/latest/developer-resources/database-apis-reference/rest/relations.md 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/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..cb131f3d35 --- /dev/null +++ b/docs/developer-docs/latest/developer-resources/database-apis-reference/rest/relations.md @@ -0,0 +1,229 @@ +--- +title: Reordering relations +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 + + +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. The `connect`, `disconnect`, and `set` attributes, passed in the body of POST or PUT requests, have different behaviors: + +- `connect` and `disconnect` perform partial updates +- `set` performs a full update, effectively replacing all existing relations + +Using the longhand syntax with `connect` allows adding [positional arguments](#longhand-syntax) to define an order for relations. + +```json +/** + * Partial update (will add/remove the specified relations) + */ + +// Using the shorthand syntax +{ + data: { + categories: { connect: [2, 4], disconnect: [5] } + } +} + +// Using the longhand syntax +{ + data: { + categories: { connect: [{ id: 2 }, { id: 4 }], disconnect: [{ id: 5 }] } + } +} + +/** + * Full update (will delete all current relations and set those ones instead) + */ + +// Using the shorthand syntax +{ + data: { + categories: { set: [2, 4] } + } +} + +// Using the longhand syntax +{ + data: { + categories: { set: [{ id: 2 }, { id: 4 }] } + } +} +``` + +## `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. + +### Shorthand syntax + +With the shorthand syntax, pass an array of ids of relations to create. + +**Example:** + +Passing the following example of body request adds the `categories` entries with ids `2` and `4` to a content-type's relations: + +```json +{ + data: { + categories: { connect: [2, 4] } + } +} +``` + +### Longhand syntax + +With the longhand syntax, you can pass optional positional arguments 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. + +`position` accepts 4 different positional attributes: + +| Parameter name and syntax | Description | +|---------------------------|-------------| +| `before: id` | Positions the relation before the given `id` | +| `after: id` | Positions the relation after the given `id` | +| `start` | Positions the relation at the start of the existing list of relations. | +| `end` | Positions the relation at the end of the existing list of relations. | + +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 and connect operations will be treated sequentially (see elaborated example below). +::: + +**Basic example:** + +Given the following record in the database: + +```json +categories: [ + { id: 1, order: 1 } + { id: 2, order: 2 } +] +``` + +sending the following in the request body of a PUT or POST request will create a third relation of `id` `3` and position it before the relation with `id` `2`: + +```json +categories: { + connect: [ + { id: 3, position: { before: 2 } }, // It should be placed before relation id=2 + ] +} +``` + +**Combined example:** + +Sending the following example in the request body of a PUT or POST request updates multiple relations: + +```json +categories: { + connect: [ + // By default positional info will be end: true + { id: 6, position: { after: 1} }, // It should be after relation with id 1 + { id: 7, position: { before: 2 }}, // It should be before relation with id 2 + { id: 8, position: { end: true }}, // It should be at the end + { id: 9 }, // It should also be at the end + { id: 10, position: { start: true }} // It should be at the start + ] +} +``` + +The resulting database record could be the following: + +```json +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. + +### Shorthand syntax + +With the shorthand syntax, pass an array of ids of relations to be removed. + +**Example:** + +Passing the following example of a body request removes the categories with the id 4 from the content type's relations: + +```json +categories: { + disconnect: [4] +} +``` + +### Longhand syntax + +With the longhand syntax, pass an array of objects with the `id` property for each relation to remove. + +**Example:** + +Passing the following example of a body request removes the categories with the id 4 from the content type's relations: + +```json +categories: { + disconnect: [ + { 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. + +### Shorthand syntax + +With the shorthand syntax, pass an array of ids of relations to be set. + +**Example:** + +Passing the following example of a body request will override all existing relations previously defined for `categories` and replace them only with ids `2` and `4`: + +```json +{ + data: { + categories: { set: [2, 4] } + } +} +``` + +### Longhand syntax + +With the longhand syntax, pass an array of objects with the `id` property for each relation to set. + +**Example:** + +Passing the following example of a body request will override all existing relations previously defined for `categories` and replace them only with ids `2` and `4`: + +```json +{ + data: { + categories: { + set: [ + { id: 2 }, + { id: 4 } + ] + } + } +} +``` From 8dd4ddf1455dd1adf541626026b24410ca2fa695 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 8 Dec 2022 09:42:26 +0100 Subject: [PATCH 02/38] Add user guide link --- .../database-apis-reference/rest/relations.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 index cb131f3d35..e5c694b1a0 100644 --- 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 @@ -6,8 +6,7 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/developer-resources/d # Managing relations through the REST API - -Relations between content-types can be managed through the [admin panel]() or through REST requests sent to the Content API. +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 requests sent to the Content API. Relations can be added, updated, or removed through the Content API. The `connect`, `disconnect`, and `set` attributes, passed in the body of POST or PUT requests, have different behaviors: From f2089494b35c5eea08d4f3a4cd63a488d93b99e1 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 8 Dec 2022 09:51:03 +0100 Subject: [PATCH 03/38] Improve formatting --- .../database-apis-reference/rest/relations.md | 30 ++++++++++++------- 1 file changed, 20 insertions(+), 10 deletions(-) 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 index e5c694b1a0..227b51c2f2 100644 --- 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 @@ -13,8 +13,6 @@ Relations can be added, updated, or removed through the Content API. The `connec - `connect` and `disconnect` perform partial updates - `set` performs a full update, effectively replacing all existing relations -Using the longhand syntax with `connect` allows adding [positional arguments](#longhand-syntax) to define an order for relations. - ```json /** * Partial update (will add/remove the specified relations) @@ -53,6 +51,8 @@ Using the longhand syntax with `connect` allows adding [positional arguments](#l } ``` +Using the longhand syntax with `connect` allows adding [positional arguments](#longhand-syntax) to define an order for relations. + ## `connect` Using `connect` in the body of a request performs a partial update, adding specified relations. @@ -85,18 +85,22 @@ The longhand syntax accepts an array of objects, each object containing the `id` | Parameter name and syntax | Description | |---------------------------|-------------| -| `before: id` | Positions the relation before the given `id` | -| `after: id` | Positions the relation after the given `id` | +| `before: id` | Positions the relation before the given `id`. | +| `after: id` | Positions the relation after the given `id`. | | `start` | Positions the relation at the start of the existing list of relations. | | `end` | Positions the relation at the end of the existing list of relations. | 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 and connect operations will be treated sequentially (see elaborated example below). +Since `connect` is an array, the order of operations is important as they will be treated sequentially (see combined example below). ::: -**Basic example:** +**Examples:** + +:::: tabs card + +::: tab Basic example Given the following record in the database: @@ -117,7 +121,9 @@ categories: { } ``` -**Combined example:** +::: + +::: tab Combined example Sending the following example in the request body of a PUT or POST request updates multiple relations: @@ -148,6 +154,10 @@ categories: [ ] ``` +::: + +:::: + ## `disconnect` Using `disconnect` in the body of a request performs a partial update, removing specified relations. @@ -160,7 +170,7 @@ With the shorthand syntax, pass an array of ids of relations to be removed. **Example:** -Passing the following example of a body request removes the categories with the id 4 from the content type's relations: +Passing the following example of a body request removes the categories with `id` `4` from the content type's relations: ```json categories: { @@ -196,7 +206,7 @@ With the shorthand syntax, pass an array of ids of relations to be set. **Example:** -Passing the following example of a body request will override all existing relations previously defined for `categories` and replace them only with ids `2` and `4`: +Passing the following example of a body request will override all existing relations previously defined for `categories` and replace them only with `id` `2` and `4`: ```json { @@ -212,7 +222,7 @@ With the longhand syntax, pass an array of objects with the `id` property for ea **Example:** -Passing the following example of a body request will override all existing relations previously defined for `categories` and replace them only with ids `2` and `4`: +Passing the following example of a body request will override all existing relations previously defined for `categories` and replace them only with `id` `2` and `4`: ```json { From b095f68bfc036f5562bb4fe71966e92e480dd33e Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 8 Dec 2022 18:44:38 +0100 Subject: [PATCH 04/38] Add beta badge --- .../database-apis-reference/rest/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 227b51c2f2..65cd876f7f 100644 --- 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 @@ -4,7 +4,7 @@ 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 +# Managing relations through the REST API 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 requests sent to the Content API. From a6781d9191ee3df5b976383255c86588d8e5fb78 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 8 Dec 2022 18:45:21 +0100 Subject: [PATCH 05/38] Fix tense Co-authored-by: Shaun Brown <97027841+StrapiShaun@users.noreply.github.com> --- .../database-apis-reference/rest/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 65cd876f7f..b5f678d0f5 100644 --- 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 @@ -111,7 +111,7 @@ categories: [ ] ``` -sending the following in the request body of a PUT or POST request will create a third relation of `id` `3` and position it before the relation with `id` `2`: +sending the following in the request body of a PUT or POST request creates a third relation of `id` `3` and position it before the relation with `id` `2`: ```json categories: { From a9b46549f13297e5564fe7eecfc70c8ab8d19e2b Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 12 Dec 2022 18:11:07 +0100 Subject: [PATCH 06/38] Mention connect & disconnect vs. set alone --- .../database-apis-reference/rest/relations.md | 2 ++ 1 file changed, 2 insertions(+) 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 index b5f678d0f5..2242f570ee 100644 --- 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 @@ -13,6 +13,8 @@ Relations can be added, updated, or removed through the Content API. The `connec - `connect` and `disconnect` perform partial updates - `set` performs a full update, effectively replacing all existing relations +`connect` and `disconnect` can be passed together while `set` should be used alone. + ```json /** * Partial update (will add/remove the specified relations) From 24642c8a4d0ca9728e5ddad3f8f25fab41829302 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 12 Dec 2022 18:11:25 +0100 Subject: [PATCH 07/38] Format code blocks in intro --- .../database-apis-reference/rest/relations.md | 22 ++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) 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 index 2242f570ee..9da1b1d014 100644 --- 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 @@ -23,14 +23,25 @@ Relations can be added, updated, or removed through the Content API. The `connec // Using the shorthand syntax { data: { - categories: { connect: [2, 4], disconnect: [5] } + categories: { + connect: [2, 4], + disconnect: [5] + } } } // Using the longhand syntax { data: { - categories: { connect: [{ id: 2 }, { id: 4 }], disconnect: [{ id: 5 }] } + categories: { + connect: [ + { id: 2 }, + { id: 4 } + ], + disconnect: [ + { id: 5 } + ] + } } } @@ -48,7 +59,12 @@ Relations can be added, updated, or removed through the Content API. The `connec // Using the longhand syntax { data: { - categories: { set: [{ id: 2 }, { id: 4 }] } + categories: { + set: [ + { id: 2 }, + { id: 4 } + ] + } } } ``` From 595efadd2644cd4ca5513fa5aa92b1dd0de808e3 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 12 Dec 2022 18:11:39 +0100 Subject: [PATCH 08/38] Add type column to positional arguments --- .../database-apis-reference/rest/relations.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) 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 index 9da1b1d014..a86d23200f 100644 --- 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 @@ -101,12 +101,12 @@ The longhand syntax accepts an array of objects, each object containing the `id` `position` accepts 4 different positional attributes: -| Parameter name and syntax | Description | -|---------------------------|-------------| -| `before: id` | Positions the relation before the given `id`. | -| `after: id` | Positions the relation after the given `id`. | -| `start` | Positions the relation at the start of the existing list of relations. | -| `end` | Positions the relation at the end of the existing list of relations. | +| Parameter name and syntax | Description | Type | +|---------------------------|-------------|------| +| `before: id` | Positions the relation before the given `id`. | `id` is an entry id | +| `after: id` | Positions the relation after the given `id`. | `id` is an entry id | +| `start` | Positions the relation at the start of the existing list of relations. | Boolean | +| `end` | Positions the relation at the end of the existing list of relations. | Boolean | The `position` argument is optional and defaults to `position: { end: true }`. From fcff67f6d0343fad530def880d86c3d9510469e1 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 12 Dec 2022 18:11:56 +0100 Subject: [PATCH 09/38] Fix tense usage --- .../database-apis-reference/rest/relations.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) 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 index a86d23200f..360313b0d9 100644 --- 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 @@ -149,16 +149,16 @@ Sending the following example in the request body of a PUT or POST request updat categories: { connect: [ // By default positional info will be end: true - { id: 6, position: { after: 1} }, // It should be after relation with id 1 - { id: 7, position: { before: 2 }}, // It should be before relation with id 2 - { id: 8, position: { end: true }}, // It should be at the end - { id: 9 }, // It should also be at the end - { id: 10, position: { start: true }} // It should be at the start + { id: 6, position: { after: 1} }, // It will be after relation with id 1 + { id: 7, position: { before: 2 }}, // It will be before relation with id 2 + { id: 8, position: { end: true }}, // It will be at the end + { id: 9 }, // It will also be at the end + { id: 10, position: { start: true }} // It will be at the start ] } ``` -The resulting database record could be the following: +The resulting database record will be the following: ```json categories: [ From 1ba365e78d6c3d09de236752254c65b489d53223 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 12 Dec 2022 18:12:16 +0100 Subject: [PATCH 10/38] Fix missing spaces in code example --- .../database-apis-reference/rest/relations.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) 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 index 360313b0d9..09c1af8b48 100644 --- 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 @@ -162,13 +162,13 @@ The resulting database record will be the following: ```json 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} + { 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 } ] ``` From af0760c69bc71043f58fd9c90bdcb8fbf74ca715 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 12 Dec 2022 18:12:42 +0100 Subject: [PATCH 11/38] Fix wording --- .../database-apis-reference/rest/relations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 09c1af8b48..fad269d7df 100644 --- 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 @@ -120,7 +120,7 @@ Since `connect` is an array, the order of operations is important as they will b ::: tab Basic example -Given the following record in the database: +Consider the following record in the database: ```json categories: [ @@ -129,7 +129,7 @@ categories: [ ] ``` -sending the following in the request body of a PUT or POST request creates a third relation of `id` `3` and position it before the relation with `id` `2`: +Sending the following in the request body to update an entry creates a third relation of `id` `3` and position it before the relation with `id` `2`: ```json categories: { From 2ed684c9a04c05c5e23a34b2668c835d7269a282 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 12 Dec 2022 19:44:27 +0100 Subject: [PATCH 12/38] Add backlink to main REST API docs --- .../database-apis-reference/rest/relations.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) 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 index fad269d7df..0607f6261b 100644 --- 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 @@ -6,7 +6,7 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/developer-resources/d # Managing relations through the REST API -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 requests sent to the Content API. +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 added, updated, or removed through the Content API. The `connect`, `disconnect`, and `set` attributes, passed in the body of POST or PUT requests, have different behaviors: @@ -46,8 +46,6 @@ Relations can be added, updated, or removed through the Content API. The `connec } /** - * Full update (will delete all current relations and set those ones instead) - */ // Using the shorthand syntax { @@ -56,7 +54,6 @@ Relations can be added, updated, or removed through the Content API. The `connec } } -// Using the longhand syntax { data: { categories: { From 4a071d115642d1b1287142ed71302b39590c4671 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 12 Dec 2022 19:45:18 +0100 Subject: [PATCH 13/38] Replace intro code blocks with tabs and API calls components --- .../database-apis-reference/rest/relations.md | 151 ++++++++++++++++-- 1 file changed, 141 insertions(+), 10 deletions(-) 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 index 0607f6261b..0094b7b702 100644 --- 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 @@ -15,12 +15,18 @@ Relations can be added, updated, or removed through the Content API. The `connec `connect` and `disconnect` can be passed together while `set` should be used alone. -```json -/** - * Partial update (will add/remove the specified relations) - */ +Different syntaxes can be used and are detailed in the following recapitulative examples and in the following sections. Using the longhand syntax with `connect` allows adding [positional arguments](#longhand-syntax) to define an order for relations. + +:::::: tabs card + +::::: tab Partial update with connect & disconnect +:::: api-call -// Using the shorthand syntax +::: request Example request using the shorthand syntax + +`PUT http://localhost:1337/api/restaurants/1` + +```json { data: { categories: { @@ -29,8 +35,32 @@ Relations can be added, updated, or removed through the Content API. The `connec } } } +``` + +::: -// Using the longhand syntax +::: response Example response + +```json +{ + "data": { + "id": 1, + "attributes": {}, + "meta": {} + }, + "meta": {} +} +``` + +:::: + +:::: api-call + +::: request Example request using the longhand syntax + +`PUT http://localhost:1337/api/restaurants/1` + +```json { data: { categories: { @@ -44,16 +74,100 @@ Relations can be added, updated, or removed through the Content API. The `connec } } } +``` + +::: -/** +::: response Example response -// Using the shorthand syntax +```json +{ + "data": { + "id": 1, + "attributes": {}, + "meta": {} + }, + "meta": {} +} +``` + +:::: + +::::: + +::::: tab Full update with set + +:::: api-call + +::: request Example request using the shortest possible syntax + +`PUT http://localhost:1337/api/restaurants/1` + +```json { data: { - categories: { set: [2, 4] } + categories: [2, 4] + } +} +``` + +::: + +::: response Example response + +```json +{ + "data": { + "id": 1, + "attributes": {}, + "meta": {} + }, + "meta": {} +} +``` + +:::: + +:::: api-call + +::: request Example request using the shorthand syntax + +`PUT http://localhost:1337/api/restaurants/1` + +```json +{ + data: { + categories: { + set: [2, 4] + } } } +``` + +::: + +::: response Example response + +```json +{ + "data": { + "id": 1, + "attributes": {}, + "meta": {} + }, + "meta": {} +} +``` + +:::: + +:::: api-call + +::: request Example request using the longhand syntax + +`PUT http://localhost:1337/api/restaurants/1` +```json { data: { categories: { @@ -66,7 +180,24 @@ Relations can be added, updated, or removed through the Content API. The `connec } ``` -Using the longhand syntax with `connect` allows adding [positional arguments](#longhand-syntax) to define an order for relations. +::: + +::: response Example response + +```json +{ + "data": { + "id": 1, + "attributes": {}, + "meta": {} + }, + "meta": {} +} +``` + +:::: +::::: +:::::: ## `connect` From 61cb3b81a42d0fefc6b0152f2f197c8d70154b10 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 12 Dec 2022 19:45:45 +0100 Subject: [PATCH 14/38] Fix CSS locally so that API calls don't oversize tabs --- .../database-apis-reference/rest/relations.md | 8 ++++++++ 1 file changed, 8 insertions(+) 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 index 0094b7b702..8004c26a40 100644 --- 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 @@ -4,6 +4,14 @@ 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 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. From 7df3a9ef0cbf7e1e7dc337fa7694bc0c1c086df3 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 12 Dec 2022 19:46:03 +0100 Subject: [PATCH 15/38] Add note about syntaxes --- .../database-apis-reference/rest/relations.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) 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 index 8004c26a40..01b94bb4d8 100644 --- 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 @@ -207,12 +207,31 @@ Different syntaxes can be used and are detailed in the following recapitulative ::::: :::::: +::: note + +- The syntaxes described in this documentation are specially made for one-to-many, many-to-many and many-ways relationships. +- For one-to-one, many-to-one and one-way, the syntaxes are also supported but: + - Only the last relation will be used. + - A simpler format can also be used: + + ```json + { + data: { + category: 2 + } + } + ``` + +::: + + ## `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. + ### Shorthand syntax With the shorthand syntax, pass an array of ids of relations to create. From a9471d5be26202d8ab9870b3ba4854402a273019 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 12 Dec 2022 19:46:15 +0100 Subject: [PATCH 16/38] Fix tenses --- .../database-apis-reference/rest/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 01b94bb4d8..a7542d0e4f 100644 --- 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 @@ -289,7 +289,7 @@ Sending the following in the request body to update an entry creates a third rel ```json categories: { connect: [ - { id: 3, position: { before: 2 } }, // It should be placed before relation id=2 + { id: 3, position: { before: 2 } }, // It will be placed before relation id=2 ] } ``` From dc4284fa53b20c49811342ded87eb22092ef7c85 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 12 Dec 2022 19:50:19 +0100 Subject: [PATCH 17/38] Remove POST mention in example Could be confusing as there would be no record in the case of a POST request. --- .../database-apis-reference/rest/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index a7542d0e4f..c0035457bf 100644 --- 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 @@ -298,7 +298,7 @@ categories: { ::: tab Combined example -Sending the following example in the request body of a PUT or POST request updates multiple relations: +Sending the following example in the request body of a PUT request updates multiple relations: ```json categories: { From b410e90d09fef2d83f86ea79cc200e1d9955ad37 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Mon, 12 Dec 2022 19:51:22 +0100 Subject: [PATCH 18/38] Add "context" before Combined example --- .../database-apis-reference/rest/relations.md | 9 +++++++++ 1 file changed, 9 insertions(+) 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 index c0035457bf..d910bd4569 100644 --- 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 @@ -298,6 +298,15 @@ categories: { ::: tab Combined example +Consider the following record in the database: + +```json +categories: [ + { id: 1, order: 1 } + { id: 2, order: 2 } +] +``` + Sending the following example in the request body of a PUT request updates multiple relations: ```json From 9441dc14b830734addee6d50978bca4366c95409 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 13 Dec 2022 11:56:21 +0100 Subject: [PATCH 19/38] Rework the whole document --- .../database-apis-reference/rest/relations.md | 323 +++++++++++++++++- 1 file changed, 317 insertions(+), 6 deletions(-) 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 index d910bd4569..3aa0edf109 100644 --- 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 @@ -16,14 +16,325 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/developer-resources/d 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 added, updated, or removed through the Content API. The `connect`, `disconnect`, and `set` attributes, passed in the body of POST or PUT requests, have different behaviors: +Relations can be added, updated, or removed through the Content API by passing parameters in the body of the request: -- `connect` and `disconnect` perform partial updates -- `set` performs a full update, effectively replacing all existing relations +| Parameter name | Description | Type of update | +|-----------------|------------------|----------------| +| [`connect`](#connect) | Adds relation(s).

Can be used in combination with `disconnect`.

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

Can be used in combination with `connect`. | Partial +| [`set`](#set) | Sets relations, replacing all the existing ones.

Must be used alone. | Full -`connect` and `disconnect` can be passed together while `set` should be used alone. +Using `connect` allows adding [positional arguments](#relations-reordering) 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](#relations-reordering). + +`connect` can be used in combination with [`disconnect`](#disconnect). + +
-Different syntaxes can be used and are detailed in the following recapitulative examples and in the following sections. Using the longhand syntax with `connect` allows adding [positional arguments](#longhand-syntax) to define an order for relations. + +:::::: tabs card + +::::: tab Shorthand syntax example + +::: request Example request using the shorthand syntax + +`PUT http://localhost:1337/api/restaurants/1` + +```json +{ + data: { + categories: { + connect: [2, 4], + } + } +} +``` + +::: + +::::: + +::::: tab Longhand syntax example + +::: 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 relation 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). +::: + +::::: tabs card + +:::: tab Basic example + +Consider the following record in the database: + +```json +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`: + +::: 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, order: 1 } + { id: 2, order: 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 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: + +```json +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`](#connect). + +
+ +:::::: tabs card + +::::: tab Shorthand syntax example + +::: request Example request using the shorthand syntax + +`PUT http://localhost:1337/api/restaurants/1` + +```json +{ + data: { + categories: { + disconnect: [2, 4], + } + } +} +``` + +::: + +::::: + +::::: tab Longhand syntax example + +::: 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. + +| 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 + +::: 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 + +::: request Example request using the longhand syntax with set + +`PUT http://localhost:1337/api/restaurants/1` + +```json +{ + data: { + categories: { + set: [ + { id: 2 }, + { id: 4 } + ], + } + } +} +``` + +::: + +::::: +:::::: + + + From 17fcbe55d1de2c79308204f4f52efba6ebd5de2f Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 13 Dec 2022 11:59:31 +0100 Subject: [PATCH 20/38] Remove commented out parts used for the draft --- .../database-apis-reference/rest/relations.md | 397 ------------------ 1 file changed, 397 deletions(-) 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 index 3aa0edf109..99beee2ad3 100644 --- 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 @@ -332,400 +332,3 @@ Omitting any parameter is equivalent to using `set`.
For instance, the follo ::::: :::::: - - - From 9669c77acbbb2902b4c95db25f6ecef40aff07b2 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 13 Dec 2022 14:28:18 +0100 Subject: [PATCH 21/38] =?UTF-8?q?Fix=20grammar:=20position=20=E2=86=92=20p?= =?UTF-8?q?ositions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Shaun Brown <97027841+StrapiShaun@users.noreply.github.com> --- .../database-apis-reference/rest/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 99beee2ad3..82edd8af9f 100644 --- 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 @@ -131,7 +131,7 @@ categories: [ ] ``` -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`: +Sending the following request updates a `restaurant` entry and creates a third relation of `id` `3` for the `categories` attribute and positions it before the relation with `id` `2`: ::: request Example request to update the position of one relation From 9bca6778ae458c20b39f3de421bf562d6c59dd6c Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Wed, 14 Dec 2022 11:59:10 +0100 Subject: [PATCH 22/38] Update title (YAML) --- .../database-apis-reference/rest/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 82edd8af9f..9c94c01d27 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: Reordering relations +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 --- From 2679214910b77a4fd21ba3100f1033fa133c40a0 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Wed, 21 Dec 2022 15:49:40 +0100 Subject: [PATCH 23/38] Update formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pierre Noël --- .../database-apis-reference/rest/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 9c94c01d27..b8f16b5243 100644 --- 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 @@ -37,7 +37,7 @@ Using `connect` in the body of a request performs a partial update, adding speci | Syntax type | Syntax example | | ------------|----------------| | shorthand | `connect: [2, 4]` -| longhand | ```connect: [ {id: 2}, {id: 4} ]``` | +| longhand | ```connect: [{ id: 2 }, { id: 4 }]``` | You can also use the longhand syntax to [reorder relations](#relations-reordering). From a94a06dce176c5e2a22cc0450010a5d877ffdb03 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Wed, 21 Dec 2022 15:49:57 +0100 Subject: [PATCH 24/38] Update wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pierre Noël --- .../database-apis-reference/rest/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index b8f16b5243..fbd217a793 100644 --- 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 @@ -97,7 +97,7 @@ You can also use the longhand syntax to [reorder relations](#relations-reorderin 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. +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 add 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)). From 299cec0adae5ec5ba6dcd59e5f5b29640c47d818 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Wed, 21 Dec 2022 15:50:18 +0100 Subject: [PATCH 25/38] Update code formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pierre Noël --- .../database-apis-reference/rest/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index fbd217a793..27ce01ea34 100644 --- 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 @@ -214,7 +214,7 @@ Using `disconnect` in the body of a request performs a partial update, removing | Syntax type | Syntax example | | ------------|----------------| | shorthand | `disconnect: [2, 4]` -| longhand | ```disconnect: [ {id: 2}, {id: 4} ]``` | +| longhand | ```disconnect: [{ id: 2 }, { id: 4 }]``` | `disconnect` can be used in combination with [`connect`](#connect). From 5908755de9459d7518d62e291a628ac5a0340f37 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Wed, 21 Dec 2022 15:50:31 +0100 Subject: [PATCH 26/38] Update code formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pierre Noël --- .../database-apis-reference/rest/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 27ce01ea34..af0d5bda91 100644 --- 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 @@ -275,7 +275,7 @@ Using `set` performs a full update, replacing all existing relations with the on | Syntax type | Syntax example | | ----------- | ------------------------------- | | shorthand | `set: [2, 4]` | -| longhand | ```set: [ {id: 2}, {id: 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). From 6194586de8ad860ae32d351d812d27ee7d9a118f Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Wed, 21 Dec 2022 15:50:47 +0100 Subject: [PATCH 27/38] Update code formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pierre Noël --- .../database-apis-reference/rest/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index af0d5bda91..2afa35dd10 100644 --- 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 @@ -282,7 +282,7 @@ As `set` replaces all existing relations, it should not be used in combination w ::: 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: [{ 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)) ::: From ecd30e5bc663c9ea80006fa3c28e9f888340038e Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Wed, 21 Dec 2022 15:51:13 +0100 Subject: [PATCH 28/38] Update wording Co-authored-by: Gustav Hansen --- .../database-apis-reference/rest/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 2afa35dd10..48d70f22c5 100644 --- 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 @@ -22,7 +22,7 @@ Relations can be added, updated, or removed through the Content API by passing p |-----------------|------------------|----------------| | [`connect`](#connect) | Adds relation(s).

Can be used in combination with `disconnect`.

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

Can be used in combination with `connect`. | Partial -| [`set`](#set) | Sets relations, replacing all the existing ones.

Must be used alone. | Full +| [`set`](#set) | Set entities to a specific set. Using `set` will overwrite all existing connections to other entities.

It can not be used in combination with `connect` or `disconnect`. | Full Using `connect` allows adding [positional arguments](#relations-reordering) to define an order for relations. From 5ec5b05206117e5c07b2557fd88307f20fe6517c Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 17 Jan 2023 11:04:27 +0100 Subject: [PATCH 29/38] =?UTF-8?q?Replace:=20remove=20=E2=86=92=20disconnec?= =?UTF-8?q?t?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gustav Hansen --- .../database-apis-reference/rest/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 48d70f22c5..ad4a0ad587 100644 --- 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 @@ -21,7 +21,7 @@ Relations can be added, updated, or removed through the Content API by passing p | Parameter name | Description | Type of update | |-----------------|------------------|----------------| | [`connect`](#connect) | Adds relation(s).

Can be used in combination with `disconnect`.

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

Can be used in combination with `connect`. | 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.

It can not be used in combination with `connect` or `disconnect`. | Full Using `connect` allows adding [positional arguments](#relations-reordering) to define an order for relations. From cce73a17e0988bdc2101710d5cdf2befd3f01929 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 17 Jan 2023 11:04:51 +0100 Subject: [PATCH 30/38] =?UTF-8?q?Replace:=20add=20=E2=86=92=20connect?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gustav Hansen --- .../database-apis-reference/rest/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index ad4a0ad587..b5ca3bd0a7 100644 --- 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 @@ -20,7 +20,7 @@ Relations can be added, updated, or removed through the Content API by passing p | Parameter name | Description | Type of update | |-----------------|------------------|----------------| -| [`connect`](#connect) | Adds relation(s).

Can be used in combination with `disconnect`.

Can be used with [positional arguments](#relations-reordering) to define an order for relations. | Partial +| [`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.

It can not be used in combination with `connect` or `disconnect`. | Full From 83d38d1981a45010137583cb30ac715d9138d09a Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 17 Jan 2023 11:04:10 +0100 Subject: [PATCH 31/38] Reword 'connecting' --- .../database-apis-reference/rest/relations.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 index 48d70f22c5..f569946fc7 100644 --- 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 @@ -14,9 +14,11 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/developer-resources/d # 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 added, updated, or removed through the Content API by passing parameters in the body of the request: +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 | |-----------------|------------------|----------------| From 7899596d62b33d8366f4bc1a88a8bad7ca901571 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 17 Jan 2023 11:38:28 +0100 Subject: [PATCH 32/38] Fix intro table --- .../database-apis-reference/rest/relations.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) 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 index e48bcc01ac..9e92f5c527 100644 --- 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 @@ -24,11 +24,7 @@ Relations can be connected, disconnected or set through the Content API by passi |-----------------|------------------|----------------| | [`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.

It can not be used in combination with `connect` or `disconnect`. | Full - -Using `connect` allows adding [positional arguments](#relations-reordering) to define an order for relations. - -
+| [`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` From 015282332d0c08d50e6ea8e971f2bc63d20a6a6b Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 17 Jan 2023 11:39:06 +0100 Subject: [PATCH 33/38] Mention numbers are ids --- .../database-apis-reference/rest/relations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 index 9e92f5c527..3e3b47d343 100644 --- 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 @@ -30,7 +30,7 @@ Relations can be connected, disconnected or set through the Content API by passi Using `connect` in the body of a request performs a partial update, adding specified relations. -`connect` accepts either a shorthand or a longhand syntax. +`connect` accepts either a shorthand or a longhand syntax. In the following examples, numbers refers to entity ids: | Syntax type | Syntax example | | ------------|----------------| @@ -207,7 +207,7 @@ categories: [ Using `disconnect` in the body of a request performs a partial update, removing specified relations. -`disconnect` accepts either a shorthand or a longhand syntax. +`disconnect` accepts either a shorthand or a longhand syntax. In the following examples, numbers refers to entity ids: | Syntax type | Syntax example | | ------------|----------------| @@ -268,7 +268,7 @@ Using `disconnect` in the body of a request performs a partial update, removing 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. +`set` accepts a shorthand or a longhand syntax. In the following examples, numbers refers to entity ids: | Syntax type | Syntax example | | ----------- | ------------------------------- | From d7c2addb29d3fc4b202d428c20b4c18aca3d9303 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 17 Jan 2023 11:39:41 +0100 Subject: [PATCH 34/38] Improve wording and make it more consistent --- .../database-apis-reference/rest/relations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 index 3e3b47d343..eee3e9f8ea 100644 --- 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 @@ -28,7 +28,7 @@ Relations can be connected, disconnected or set through the Content API by passi ## `connect` -Using `connect` in the body of a request performs a partial update, adding specified relations. +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: @@ -95,7 +95,7 @@ You can also use the longhand syntax to [reorder relations](#relations-reorderin 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 add the relation. +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)). @@ -205,7 +205,7 @@ categories: [ ## `disconnect` -Using `disconnect` in the body of a request performs a partial update, removing specified relations. +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: From 28642eb302fbd7e6f2fa39e2eb75d5e4062ae898 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 17 Jan 2023 11:40:09 +0100 Subject: [PATCH 35/38] Remove 'order' from examples at it's not visible to the user --- .../database-apis-reference/rest/relations.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) 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 index eee3e9f8ea..916105cf4f 100644 --- 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 @@ -124,8 +124,8 @@ Consider the following record in the database: ```json categories: [ - { id: 1, order: 1 } - { id: 2, order: 2 } + { id: 1 } + { id: 2 } ] ``` @@ -156,8 +156,8 @@ Consider the following record in the database: ```json categories: [ - { id: 1, order: 1 } - { id: 2, order: 2 } + { id: 1 } + { id: 2 } ] ``` @@ -189,13 +189,13 @@ Omitting the `position` argument defaults (as in `id: 9` defaults to `position: ```json 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 } + { id: 10 }, + { id: 1 }, + { id: 6 }, + { id: 7 }, + { id: 2 }, + { id: 8 }, + { id: 9 } ] ``` From 7286a38206779efb4772f11430e7ecfa330852ce Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 17 Jan 2023 11:40:26 +0100 Subject: [PATCH 36/38] Mention we can't connect a relation more than once --- .../database-apis-reference/rest/relations.md | 4 ++++ 1 file changed, 4 insertions(+) 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 index 916105cf4f..5d744a82e7 100644 --- 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 @@ -116,6 +116,10 @@ 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). ::: +:::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 From 780b6d7f60b5cc1d0c7b9403d968ce94d4b33fd2 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 17 Jan 2023 11:40:43 +0100 Subject: [PATCH 37/38] Be more explicit with examples' goal --- .../database-apis-reference/rest/relations.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) 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 index 5d744a82e7..1f5d4c2601 100644 --- 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 @@ -43,11 +43,12 @@ You can also use the longhand syntax to [reorder relations](#relations-reorderin
- :::::: 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` @@ -68,6 +69,8 @@ You can also use the longhand syntax to [reorder relations](#relations-reorderin ::::: 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` @@ -90,7 +93,6 @@ You can also use the longhand syntax to [reorder relations](#relations-reorderin ::::: :::::: - ### Relations reordering Positional arguments can be passed to the longhand syntax of `connect` to define the order of relations. @@ -133,7 +135,7 @@ categories: [ ] ``` -Sending the following request updates a `restaurant` entry and creates a third relation of `id` `3` for the `categories` attribute and positions it before the relation with `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 @@ -189,7 +191,7 @@ Sending the following example in the request body of a PUT request updates multi ::: -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: +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: [ @@ -226,6 +228,8 @@ Using `disconnect` in the body of a request performs a partial update, disconnec ::::: 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` @@ -246,6 +250,8 @@ Using `disconnect` in the body of a request performs a partial update, disconnec ::::: 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` @@ -293,6 +299,8 @@ Omitting any parameter is equivalent to using `set`.
For instance, the follo ::::: 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` @@ -313,6 +321,8 @@ Omitting any parameter is equivalent to using `set`.
For instance, the follo ::::: 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` From cc8ff433d2437d40f156e4440840cde84a4b8ce8 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 17 Jan 2023 14:36:13 +0100 Subject: [PATCH 38/38] Mention relations management in Entity Service and Query Engine APIs --- .../database-apis-reference/entity-service/crud.md | 4 ++++ .../database-apis-reference/query-engine/single-operations.md | 4 ++++ .../database-apis-reference/snippets/managing-relations.md | 3 +++ 3 files changed, 11 insertions(+) create mode 100644 docs/developer-docs/latest/developer-resources/database-apis-reference/snippets/managing-relations.md 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/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)). +:::