Skip to main content

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
(see entity-service-document-service)

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​

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

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:

Contribute to this page