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

Core service methods use the Document Service API#

In Strapi 5, core service methods use the Document Service API instead of the Entity Service API, with methods like findOne, update, and delete receiving a documentId instead of entityId.

In Strapi 5, core service methods use the Document Service API instead of the Entity Service API.

Breaking change description#

In Strapi v4

The core controllers and the createCoreService factory by default use the Entity Service API.
Methods such as, for instance, find, update, and delete receive an entityId.

In Strapi 5

The core controllers and the createCoreService factory use the Document Service API.
Methods such as, for instance, find, update, and delete receive a documentId.

Migration#

Notes#

Some core methods are calling super.find(ctx) which internally calls entity service methods in Strapi v4, while they call Document Service API methods in Strapi 5. This may result in some queries no longer working, or returning slightly different results from expecting.

The following examples show how the code should be updated:

In Strapi v4:

const { createCoreService } = require('@strapi/strapi').factories;

module.exports = createCoreService('api::address.address', {

  findOne(entityId, params) {
    // customization
    super.findOne(entityId, params);

    // or to show a bit more context
    strapi.entityService.findOne(uid, entityId, params);
  },

  update(entityId, params) {
    // customization
    super.update(entityId, params);
  },

  delete(entityId, params) {
    // customization
    super.delete(entityId, params)
  }

});

In Strapi 5:

const { createCoreService } = require('@strapi/strapi').factories;

module.exports = createCoreService('api::address.address', {

  findOne(documentId, params) {
    // customization
    super.findOne(documentId, params);

    // or to show a bit more context
    strapi.documents(uid).findOne(documentId, params);
  },

  update(documentId, params) {
    // customization
    super.update(documentId, params);
  },

  delete(documentId, params) {
    // customization
    super.delete(documentId, params)
  }
});

Manual procedure#

To update your custom code:

1. Find all calls to createCoreService with customization.
2. If any of findOne, delete, update function for a collection type are extending core methods, update them as explained in the notes.

Additionally, please refer to the Entity Service API to Document Service API migration documentation.