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
Topic | Description of the changes |
---|---|
File upload support |
|
Internationalization support | Removed the createXXLocalization mutations in favor of being able to update any locale from the main updateXXX mutation |
Draft & Publish support | Removed publicationState in favor of status to align with the new Draft & Publish behavior |
Schema changes |
|
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:
-
Enable v4 compatibility mode with the
v4ComptabilityMode
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
}
}
}
} -
Use
documentId
instead ofid
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
}
}
}
}
}
}
}
}
- 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
}
}
}
}
- 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
}
}
}
}
- 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
}
}
}