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.

This section regroups useful notes and procedures about the introduced breaking change.

🔌 Is this breaking change affecting plugins?	Yes

🤖 Is this breaking change automatically handled by a codemod?	Partly

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

This section regroups useful notes and procedures about the introduced breaking change.

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

  Info

  To ease the transition to Strapi 5, Document Service API responses still include id fields in addition to the new documentId fields.

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