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

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?	Partly

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 related breaking change entry, the step-by-step guide to upgrade to Strapi 5, and the dedicated migration guide for the Entity Service API to Document Service API transition if this applies to your custom code.