From 5de252f7bc3cdbc06e11ec5eb8af5982b2117150 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 22 Jul 2025 18:39:27 +0200 Subject: [PATCH 1/4] Expand Document Service API introduction --- docusaurus/docs/cms/api/document-service.md | 26 ++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/docusaurus/docs/cms/api/document-service.md b/docusaurus/docs/cms/api/document-service.md index b7c8225b34..80c76a566e 100644 --- a/docusaurus/docs/cms/api/document-service.md +++ b/docusaurus/docs/cms/api/document-service.md @@ -12,12 +12,32 @@ tags: # Document Service API -The Document Service API is built on top of the **Query Engine API** 2 different back-end APIs allow you to interact with your content: More details can be found in the [Content API](/cms/api/content-api) and [backend customization](/cms/backend-customization) introductions. and used to perform CRUD ([create](#create), [retrieve](#findone), [update](#update), and [delete](#delete)) operations on **documents** . +The Document Service API is built on top of the **Query Engine API** 2 different back-end APIs allow you to interact with your content:
  • The [Query Engine API](/cms/api/query-engine) is the lower-level layer that offers unrestricted access to the database, but is not aware of complex Strapi content structures such as components and dynamic zones.
  • The Document Service API is built on top of the Query Engine and is the recommended way to interact with your content while you are customizing the back end server or developing plugins.
More details can be found in the [Content API](/cms/api/content-api) and [backend customization](/cms/backend-customization) introductions. and is used to perform CRUD ([create](#create), [retrieve](#findone), [update](#update), and [delete](#delete)) operations on **documents** . -With the Document Service API, you can also [count](#count) documents and, if [Draft & Publish](/cms/features/draft-and-publish) is enabled on the content-type, perform Strapi-specific features such as [publishing](#publish)/[unpublishing](#unpublish) documents and [discarding drafts](#discarddraft). +The Document Service API also supports [counting](#count) documents and, if [Draft & Publish](/cms/features/draft-and-publish) is enabled on the content-type, performing Strapi-specific features such as [publishing](#publish)/[unpublishing](#unpublish) documents and [discarding drafts](#discarddraft). + +In Strapi 5, documents are uniquely identified by their `documentId` at the API level. + + + +**`documentId` explained: Replacing `id` from Strapi v4** + +In previous Strapi versions, the concept of `id` (used both in the Content API and as the database row identifier) was not always stable: a single entry could have multiple versions or localizations, and its numeric identifier `id` could change in cases such as duplication or import/export operations. + +To address this limitation, Strapi 5 introduced `documentId`, a 24-character alphanumeric string, as a unique and persistent identifier for a content entry, independent of its physical records. + +This new identifier is used internally in Strapi 5 to manage relationships, publishing, localization, and version history, as all possible variations of a content entry are now grouped under a single [document](/cms/api/document) concept. + +As a result, starting with Strapi 5, many APIs and services rely on `documentId` instead of `id` to ensure consistency across operations. Some APIs may still return both `documentId` and `id` to ease the transition, but using `documentId` for content queries is strongly recommended. + +For more details on the transition from `id` to `documentId`, refer to the [breaking change page](/cms/migration/v4-to-v5/breaking-changes/use-document-id) and in the [migration guide from Entity Service to Document Service API](/cms/migration/v4-to-v5/additional-resources/from-entity-service-to-document-service). + + :::strapi Entity Service API is deprecated in Strapi 5 -The Document Service API is meant to replace the Entity Service API used in Strapi v4 (). Additional information on how to transition away from the Entity Service API to the Document Service API can be found in the related [migration reference](/cms/migration/v4-to-v5/additional-resources/from-entity-service-to-document-service). +The Document Service API replaces the Entity Service API used in Strapi v4 (). + +Additional information on how to transition away from the Entity Service API to the Document Service API can be found in the [migration reference](/cms/migration/v4-to-v5/additional-resources/from-entity-service-to-document-service). ::: :::note From fa9259b4961b507d7a41c83fbda6f769101ae6e4 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 22 Jul 2025 18:39:43 +0200 Subject: [PATCH 2/4] Improve formatting for additional resources in breaking change page --- .../migration/v4-to-v5/breaking-changes/use-document-id.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes/use-document-id.md b/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes/use-document-id.md index b41bc9551c..8c933e01b5 100644 --- a/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes/use-document-id.md +++ b/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes/use-document-id.md @@ -104,4 +104,8 @@ Documents are identified by their `documentId`: A codemod will partly handle the change, but might probably add `__TODO__` items to your code since it's impossible for the codemod to automatically guess the new `documentId` of your content. -For additional information, please refer to the related [breaking change entry](/cms/migration/v4-to-v5/breaking-changes/entity-service-deprecated), the [step-by-step guide](/cms/migration/v4-to-v5/step-by-step) to upgrade to Strapi 5, and the dedicated migration guide for the [Entity Service API to Document Service API transition](/cms/migration/v4-to-v5/additional-resources/from-entity-service-to-document-service) if this applies to your custom code. +For additional information, please refer to the following resources: + +- related [breaking change entry for Entity Service API deprecation](/cms/migration/v4-to-v5/breaking-changes/entity-service-deprecated), +- [step-by-step guide](/cms/migration/v4-to-v5/step-by-step) to upgrade to Strapi 5, +- and dedicated migration guide for the [Entity Service API to Document Service API transition](/cms/migration/v4-to-v5/additional-resources/from-entity-service-to-document-service) if your custom code is affected by these changes. From 7d153dbaa0638a91d18eac0203b5f576c8009169 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 22 Jul 2025 18:41:48 +0200 Subject: [PATCH 3/4] Fine-tune introduction wording --- docusaurus/docs/cms/api/document-service.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docusaurus/docs/cms/api/document-service.md b/docusaurus/docs/cms/api/document-service.md index 80c76a566e..594140acca 100644 --- a/docusaurus/docs/cms/api/document-service.md +++ b/docusaurus/docs/cms/api/document-service.md @@ -14,7 +14,7 @@ tags: The Document Service API is built on top of the **Query Engine API** 2 different back-end APIs allow you to interact with your content:
  • The [Query Engine API](/cms/api/query-engine) is the lower-level layer that offers unrestricted access to the database, but is not aware of complex Strapi content structures such as components and dynamic zones.
  • The Document Service API is built on top of the Query Engine and is the recommended way to interact with your content while you are customizing the back end server or developing plugins.
More details can be found in the [Content API](/cms/api/content-api) and [backend customization](/cms/backend-customization) introductions. and is used to perform CRUD ([create](#create), [retrieve](#findone), [update](#update), and [delete](#delete)) operations on **documents** . -The Document Service API also supports [counting](#count) documents and, if [Draft & Publish](/cms/features/draft-and-publish) is enabled on the content-type, performing Strapi-specific features such as [publishing](#publish)/[unpublishing](#unpublish) documents and [discarding drafts](#discarddraft). +The Document Service API also supports [counting](#count) documents and, if [Draft & Publish](/cms/features/draft-and-publish) is enabled on the content-type, performing Strapi-specific operations such as [publishing](#publish), [unpublishing](#unpublish), and [discarding drafts](#discarddraft). In Strapi 5, documents are uniquely identified by their `documentId` at the API level. @@ -30,18 +30,18 @@ This new identifier is used internally in Strapi 5 to manage relationships, publ As a result, starting with Strapi 5, many APIs and services rely on `documentId` instead of `id` to ensure consistency across operations. Some APIs may still return both `documentId` and `id` to ease the transition, but using `documentId` for content queries is strongly recommended. -For more details on the transition from `id` to `documentId`, refer to the [breaking change page](/cms/migration/v4-to-v5/breaking-changes/use-document-id) and in the [migration guide from Entity Service to Document Service API](/cms/migration/v4-to-v5/additional-resources/from-entity-service-to-document-service). +For more details on the transition from `id` to `documentId`, refer to the [breaking change page](/cms/migration/v4-to-v5/breaking-changes/use-document-id) and the [migration guide from Entity Service to Document Service API](/cms/migration/v4-to-v5/additional-resources/from-entity-service-to-document-service). :::strapi Entity Service API is deprecated in Strapi 5 The Document Service API replaces the Entity Service API used in Strapi v4 (). -Additional information on how to transition away from the Entity Service API to the Document Service API can be found in the [migration reference](/cms/migration/v4-to-v5/additional-resources/from-entity-service-to-document-service). +Additional information on how to migrate from the Entity Service API to the Document Service API can be found in the [migration reference](/cms/migration/v4-to-v5/additional-resources/from-entity-service-to-document-service). ::: :::note -Relations can also be connected, disconnected, and set through the Document Service API just like with the REST API (see the [REST API relations documentation](/cms/api/rest/relations) for examples). +Relations can also be connected, disconnected, and set through the Document Service API, just like with the REST API (see the [REST API relations documentation](/cms/api/rest/relations) for examples). ::: ## `findOne()` From eceba2dcc1593031041148be8b9247765c05cab3 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 22 Jul 2025 18:48:58 +0200 Subject: [PATCH 4/4] Mention why using documentId is recommended --- docusaurus/docs/cms/api/document-service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/api/document-service.md b/docusaurus/docs/cms/api/document-service.md index 594140acca..ca2369609c 100644 --- a/docusaurus/docs/cms/api/document-service.md +++ b/docusaurus/docs/cms/api/document-service.md @@ -28,7 +28,7 @@ To address this limitation, Strapi 5 introduced `documentId`, a 24-character alp This new identifier is used internally in Strapi 5 to manage relationships, publishing, localization, and version history, as all possible variations of a content entry are now grouped under a single [document](/cms/api/document) concept. -As a result, starting with Strapi 5, many APIs and services rely on `documentId` instead of `id` to ensure consistency across operations. Some APIs may still return both `documentId` and `id` to ease the transition, but using `documentId` for content queries is strongly recommended. +As a result, starting with Strapi 5, many APIs and services rely on `documentId` instead of `id` to ensure consistency across operations. Some APIs may still return both `documentId` and `id` to ease the transition, but using `documentId` for content queries is strongly recommended, as `documentId` might be the only identifier used in future Strapi versions. For more details on the transition from `id` to `documentId`, refer to the [breaking change page](/cms/migration/v4-to-v5/breaking-changes/use-document-id) and the [migration guide from Entity Service to Document Service API](/cms/migration/v4-to-v5/additional-resources/from-entity-service-to-document-service).