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.

This page is part of the breaking changes database and provides information about the breaking change and additional instructions to migrate from Strapi v4 to Strapi 5.

🔌 Is this breaking change affecting plugins?	Yes

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

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

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

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:

/src/api/my-api-name/services/my-service.js

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:

/src/api/my-api-name/services/my-service.js

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.