Skip to content

Better explain the move to documentId #2604

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 28, 2025
Merged

Better explain the move to documentId #2604

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5de252f
Expand Document Service API introduction
pwizla Jul 22, 2025
fa9259b
Improve formatting for additional resources in breaking change page
pwizla Jul 22, 2025
7d153db
Fine-tune introduction wording
pwizla Jul 22, 2025
eceba2d
Mention why using documentId is recommended
pwizla Jul 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 24 additions & 4 deletions docusaurus/docs/cms/api/document-service.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,16 +12,36 @@ tags:

# Document Service API

The Document Service API is built on top of the **Query Engine API** <Annotation>2 different back-end APIs allow you to interact with your content: <ul><li>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.</li><li>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.</li></ul>More details can be found in the [Content API](/cms/api/content-api) and [backend customization](/cms/backend-customization) introductions.</Annotation> and used to perform CRUD ([create](#create), [retrieve](#findone), [update](#update), and [delete](#delete)) operations on **documents** <DocumentDefinition />.
The Document Service API is built on top of the **Query Engine API** <Annotation>2 different back-end APIs allow you to interact with your content: <ul><li>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.</li><li>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.</li></ul>More details can be found in the [Content API](/cms/api/content-api) and [backend customization](/cms/backend-customization) introductions.</Annotation> and is used to perform CRUD ([create](#create), [retrieve](#findone), [update](#update), and [delete](#delete)) operations on **documents** <DocumentDefinition />.

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

<ExpandableContent maxHeight="80px">

**`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, 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).

</ExpandableContent>

:::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 (<ExternalLink to="https://docs-v4.strapi.io/cms/api/entity-service" text="see Strapi v4 documentation"/>). 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 (<ExternalLink to="https://docs-v4.strapi.io/dev-docs/api/entity-service" text="see Strapi v4 documentation"/>).

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()`
Expand Down
6 changes: 5 additions & 1 deletion docusaurus/docs/cms/migration/v4-to-v5/breaking-changes/use-document-id.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.