From 59b2b20f28270b2b3871cf4607c763bbaeb778a3 Mon Sep 17 00:00:00 2001 From: meganelacheny Date: Wed, 5 Nov 2025 16:06:59 +0100 Subject: [PATCH] More clarity and precisions on multi relations support (#2796) * Add more info and precisions on multi relations support * Fix typos and mistake with Document Service API --- docusaurus/docs/cms/api/rest/relations.md | 6 +++++- docusaurus/docs/cms/backend-customization/models.md | 4 +++- docusaurus/docs/cms/features/content-type-builder.md | 4 ++++ 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docusaurus/docs/cms/api/rest/relations.md b/docusaurus/docs/cms/api/rest/relations.md index 74494aec45..79fd9e93d8 100644 --- a/docusaurus/docs/cms/api/rest/relations.md +++ b/docusaurus/docs/cms/api/rest/relations.md @@ -17,7 +17,7 @@ Defining relations between content-types (that are designated as entities in the Relations between content-types can be managed through the [admin panel](/cms/features/content-manager#relational-fields) or through [REST API](/cms/api/rest) or [Document Service API](/cms/api/document-service) requests. -Relations can be connected, disconnected or set 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. These payloads work for both single-entry relations and multi relations (one-to-many, many-to-one, many-to-many, and many-way). When a relational field allows multiple links, the API expects arrays of relation IDs and returns arrays in responses. | Parameter name | Description | Type of update | |-------------------------|-------------|----------------| @@ -25,6 +25,10 @@ Relations can be connected, disconnected or set through the Content API by passi | [`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 | +:::note +Multi relations can be managed from the REST API and the [GraphQL API](/cms/api/graphql#fetch-relations): the `connect`, `disconnect`, and `set` operations are available across both APIs. However, the [Document Service API](/cms/api/document-service) does not handle relations. +::: + :::note When [Internationalization (i18n)](/cms/features/internationalization) is enabled on the content-type, you can also pass a locale to set relations for a specific locale, as in this Document Service API example: diff --git a/docusaurus/docs/cms/backend-customization/models.md b/docusaurus/docs/cms/backend-customization/models.md index bb42117fde..a89ce419ac 100644 --- a/docusaurus/docs/cms/backend-customization/models.md +++ b/docusaurus/docs/cms/backend-customization/models.md @@ -248,7 +248,9 @@ The `uid` type is used to automatically prefill the field value in the admin pan #### Relations -Relations link content-types together. Relations are explicitly defined in the [attributes](#model-attributes) of a model with `type: 'relation'` and accept the following additional parameters: +Relations link content-types together. Strapi supports both single-entry relations (one-way and one-to-one) and multi relations where at least one side can point to several entries (one-to-many, many-to-one, many-to-many, and many-way). Multi relations are persisted as arrays in the database layer and are returned as arrays in the Content API responses. + +Relations are explicitly defined in the [attributes](#model-attributes) of a model with `type: 'relation'` and accept the following additional parameters: | Parameter | Description | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docusaurus/docs/cms/features/content-type-builder.md b/docusaurus/docs/cms/features/content-type-builder.md index 660e312b09..bf0f85b2c3 100644 --- a/docusaurus/docs/cms/features/content-type-builder.md +++ b/docusaurus/docs/cms/features/content-type-builder.md @@ -448,6 +448,10 @@ There are 6 different types of relations: - Many-to-many: Content-type A *has and belongs to many* Content-type B - Many way: Content-type A *has many* Content-type B +:::info Multi relations and single relations +Relations where at least one side can reference several entries are called multi relations. In the Content-type Builder, this includes one-to-many, many-to-one, many-to-many, and many-way relations. These relations appear as multi-select fields in the Content Manager and return arrays from the REST, GraphQL, and Document Service APIs; while single relations (one-way and one-to-one relations) return a single linked entry (see [Managing relations with API requests](/cms/api/rest/relations) for more information). +::: +