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