Skip to main content

The GraphQL API has been updated

In Strapi 5, the GraphQL API has been updated. It handles the new, flattened response format (see related breaking change), and can also now accept Relay-style queries.

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

List of changes

TopicDescription of the changes
File upload support
  • Removed uploadFile uploadFiles mutations
  • Removed updateFileInfo mutation in favor of using the updateUploadFile mutation
  • Removed removeFile mutation in favor of using the deleteUploadFile mutation
  • Removed folder queries & mutations
  • Removed createUploadFile mutation
Internationalization supportRemoved the createXXLocalization mutations in favor of being able to update any locale from the main updateXXX mutation
Draft & Publish supportRemoved publicationState in favor of status to align with the new Draft & Publish behavior
Schema changes
  • Simplified the basic queries with no meta/pagination
  • Introduced Connection to add pagination

For an extensive description of the new Strapi 5 GraphQL API, please refer to the GraphQL API reference documentation.

Migration

To gradually convert to the new GraphQL API format, follow these steps:

  1. Enable v4 compatibility mode with the v4CompatibilityMode flag in the configuration of the GraphQL plugin (see plugins configuration):

    {
    restaurants {
    data {
    id
    attributes {
    title
    image {
    data {
    id
    attributes {
    url
    }
    }
    }
    images {
    data {
    id
    attributes {
    url
    }
    }
    }
    xToOneRelation {
    data {
    id
    attributes {

    }
    }
    xToManyRelation {
    data {
    id
    attributes {
    field
    }
    }
    }
    }
    }
    meta {
    pagination {
    page
    pageSize
    }
    }
    }
    }
  2. Use documentId instead of id for contentType queries & mutations:

    {
    restaurants {
    data {
    documentId
    attributes {
    title
    image {
    data {
    documentId
    attributes {
    url
    }
    }
    }
    images {
    data {
    documentId
    attributes {
    url
    }
    }
    }
    xToOneRelation {
    data {
    documentId
    attributes {

    }
    }
    xToManyRelation {
    data {
    documentId
    attributes {
    field
    }
    }
    }
    }
    }
    meta {
    pagination {
    page
    pageSize
    }
    }
    }
    }
    {
    mutation {
    updateRestaurant(
    documentId: "some-doc-id",
    data: { title: "My great restaurant" }
    ) {
    data {
    documentId
    attributes {
    title
    image {
    data {
    documentId
    attributes {
    url
    }
    }
    }
    }
    }
    }
    }
    }
  3. Move to _connection without changing response format (only applies to queries):

    {
    # collection fields can be renamed to _connection to get a v4 compat response
    restaurants_connection {
    data {
    id
    attributes {
    title
    image {
    data {
    id
    attributes {
    url
    }
    }
    }
    # collection fields can be renamed to _connection to get a v4 compat response
    images_connection {
    data {
    id
    attributes {
    url
    }
    }
    }
    xToOneRelation {
    data {
    id
    attributes {
    field
    }
    }
    }
    # collection fields can be renamed to _connection to get a v4 compat response
    xToManyRelation_connection {
    data {
    id
    attributes {
    field
    }
    }
    }
    }
    }
    meta {
    pagination {
    page
    pageSize
    }
    }
    }
    }
  4. Remove attributes (applies to queries & mutation responses):

    {
    # collection fields can be renamed to _connection to get a v4 compat response
    restaurants_connection {
    data {
    id
    title
    image {
    data {
    id
    url
    }
    }
    # collection fields can be renamed to _connection to get a v4 compat response
    images_connection {
    data {
    id
    url
    }
    }
    xToOneRelation {
    data {
    id
    field
    }
    }
    # collection fields can be renamed to _connection to get a v4 compat response
    xToManyRelation_connection {
    data {
    id
    field
    }
    }
    }
    meta {
    pagination {
    page
    pageSize
    }
    }
    }
    }
  5. Use new naming or the simpler queries:

    {
    # Rename data to nodes & meta.pagination to pageInfo
    restaurants_connection {
    nodes {
    id
    title
    # can remove data in single Images
    image {
    id
    url
    }
    # collection fields can be renamed to _connection to get a v4 compat response
    images_connection {
    nodes {
    id
    url
    }
    }
    # can remove data in xToOne
    xToOneRelation {
    id
    field
    }
    # collection fields can be renamed to _connection to get a v4 compat response
    xToManyRelation_connection {
    nodes {
    id
    field
    }
    }
    }
    pageInfo {
    page
    pageSize
    }
    }
    }
    {
    # remove _connection & data if you don't need pagination att all
    restaurants {
    id
    title
    image {
    id
    url
    }
    # remove _connection & data
    images {
    id
    url
    }
    xToOneRelation {
    id
    field
    }
    # remove _connection & data
    xToManyRelation {
    id
    field
    }
    }
    }