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

documentId should be used instead of id in Content API calls#

In Strapi 5, the underlying API handling content is the Document Service API and documents should be called by their documentId in Content API calls (REST API & GraphQL).

Breaking change description#

In Strapi v4

Entries were identified by their id:

{
  "data": {
    // system fields
    "id": 14,
    "attributes": {
      // user fields
      "title": "Article A"
      "relation": {
        "data": {
          "id": "clkgylw7d000108lc4rw1bb6s"
          "name": "Category A"
        }
      }
    }
  }
  "meta": {
    // …
  }
}

In Strapi 5

Documents are identified by their documentId:

{
  "data": {
    // system fields
    "documentId": "clkgylmcc000008lcdd868feh",
    "locale": "en",
    // user fields
    "title": "Article A"
    "relation": {
      // system fields
      "documentId": "clkgylw7d000108lc4rw1bb6s"
      // user fields
      "name": "Category A"
    }
  }
  "meta": {
    // …
  }
}

Migration#

Notes#

• This breaking change impacts routes and relations.
• To ease the transition from v4 to Strapi 5, API calls to entries might still include an id field in their response, especially with the Document Service API. But it's recommended that you start making an habit of using documentId instead of id as it will ease handling the transition to future Strapi versions.

Migration procedure#

A codemod will partly handle the change, but might probably add __TODO__ items to your code since it's impossible for the codemod to automatically guess the new documentId of your content.

For additional information, please refer to the following resources:

• related breaking change entry for Entity Service API deprecation,
• step-by-step guide to upgrade to Strapi 5,
• and dedicated migration guide for the Entity Service API to Document Service API transition if your custom code is affected by these changes.