import Intro from '/docs/snippets/breaking-change-page-intro.md'
import MigrationIntro from '/docs/snippets/breaking-change-page-migration-intro.md'

Entity Service deprecated#

The Entity Service API is deprecated in Strapi 5 and replaced by the Document Service API, which uses documentId, returns arrays for all queries, and introduces new methods for draft and publish workflows.

The Entity Service that was used in Strapi v4 is deprecated and replaced by the new Document Service API in Strapi 5.

Breaking change description#

In Strapi v4

The Entity Service API is the go-to API to use to interact with your content-types.

In Strapi 5

The Document Service API replaces the Entity Service API from Strapi v4.

Migration#

Notes#

The following are the main topics to take into account when using the Document Service API instead of the Entity Service API from Strapi v4:

• The Document Service API expects a documentId property.
  This breaking change also affects the REST and GraphQL APIs (👉 see the related breaking change entry).

• The response returned by the findMany() function is different in Strapi v4 and Strapi 5:
  
  

  In Strapi v4:

  The findMany() function from the Entity Service API returns a single item for single types.
  

  In Strapi 5:

  The findMany() function from the Document Service API always returns arrays.
  
  To get a single item, extract the first item from the returned array, or use the findFirst() function.

• There is no findPage() method anymore in Strapi 5.
  👉 see the related breaking change entry.

• The Draft & Publish feature has been updated in Strapi 5 and this is reflected in the Document Service API:

  • publicationState is replaced by status
    👉 see the related breaking change entry.

  • New methods are introduced to handle the updated Draft & Publish feature:

    • publish(),
    • unpublish(),
    • and discardDraft().

  • The published_at property can not be used anymore to trigger the publication of content.

• The delete() function of the Document Service API returns a list of affected entries (multiple locales can be deleted all at once), while the delete() function from Strapi v4 returns only the deleted entry.

• Entity Service decorators can not be used anymore, and Document Service middlewares must be used instead.

• The Document Service API does not support file uploads.

Migration procedure#

The migration is partially handled by a codemod when using the upgrade tool.

👉 The Entity Service API to Document Service API migration reference gives additional information about which aspects are handled by the codemod and which use cases require manual migration.