GraphQL API

✋ Caution

The content of this page has not been updated to Strapi v5 yet.

☑️ Prerequisites

To use the GraphQL API, install the GraphQL plugin.

The GraphQL API allows performing queries and mutations to interact with the content-types through Strapi's GraphQL plugin. Results can be filtered, sorted and paginated.

Unified response format

Responses are unified with the GraphQL API in that:

• queries and mutations that return information for a single entry mainly use a XxxEntityResponse type
• queries and mutations that return i️nformation for multiple entries mainly use a XxxEntityResponseCollection type, which includes meta information (with pagination) in addition to the data itself

Responses can also include an error (see error handling documentation).

Example: Response formats for queries and mutations with an example 'Article' content-type

type ArticleEntityResponse {
    data: ArticleEntity
}

type ArticleEntityResponseCollection {
    data: [ArticleEntityResponse!]!
    meta: ResponseCollectionMeta!
}

query {
    article(...): ArticleEntityResponse # find one
    articles(...): ArticleEntityResponseCollection # find many
}

mutation {
    createArticle(...): ArticleEntityResponse # create
    updateArticle(...): ArticleEntityResponse # update
    deleteArticle(...): ArticleEntityResponse # delete
}

Queries

Queries in GraphQL are used to fetch data without modifying it.

We assume that the Shadow CRUD feature is enabled. For each model, the GraphQL plugin auto-generates queries and mutations that mimics basic CRUD operations (findMany, findOne, create, update, delete).

Fetch a single entry

Single entries can be found by their id.

Example query: Find the entry with id 1

query {
  document(id: 1) {
    data {
      id
      attributes {
        title
        categories {
          data {
            id
            attributes {
              name
            }
          }
        }
      }
    }
  }
}

Fetch multiple entries

Example query: Find all documents and populate 'categories' relation with the 'name' attribute

query {
  documents {
    data {
      id
      attributes {
        title
        categories {
          data {
            id
            attributes {
                name
            }
          }
        }
      }
    }
    meta {
      pagination {
        page
        pageSize
        total
        pageCount
      }
    }
  }
}

Fetch dynamic zone data

Dynamic zones are union types in graphql so you need to use fragments to query the fields.

query {
  restaurants {
    data {
      attributes {
        dynamiczone {
          __typename
          ...on ComponentDefaultClosingperiod {
            label
          }
        }
      }
    }
  }
}

Mutations

Mutations in GraphQL are used to modify data (e.g. create, update, delete data).

Create a new entry

mutation createArticle {
  createArticle(data: { title: "Hello"}) {
    data {
      id
      attributes {
        title
      }
    }
  }
}

The implementation of the mutations also supports relational attributes. For example, you can create a new User and attach many Restaurant to it by writing your query like this:

mutation {
  createUser(
    data: {
      username: "John"
      email: "john@doe.com"
      restaurants: ["1", "2"]
    }
  ) {
    data {
      id
      attributes {
        username
        email
        restaurants {
          data {
            id 
            attributes {
              name
              description
              price
            }
          }
        }
      }
    }
  }
}

Update an existing entry

mutation updateArticle {
  updateArticle(id: "1", data: { title: "Hello" }) {
    data {
      id
      attributes {
        title
      }
    }
  }
}

You can also update relational attributes by passing an ID or an array of IDs (depending on the relationship).

mutation {
  updateRestaurant(
    id: "5b5b27f8164f75c29c728110"
    data: {
      chef: "1" // User ID
    }
  }) {
    data {
      id
      attributes {
        chef {
          data {
            attributes {
              username
              email
            }
          }
        }
      }
    }
  }
}

Delete an entry

mutation deleteArticle {
  deleteArticle(id: 1) {
    data {
      id
      attributes {
        title
      }
    }
  }
}

Filters

Queries can accept a filters parameter with the following syntax:

filters: { field: { operator: value } }

Logical operators (and, or, not) can also be used and accept arrays of objects.

The following operators are available:

Operator	Description
eq	Equal
ne	Not equal
lt	Less than
lte	Less than or equal to
gt	Greater than
gte	Greater than or equal to
in	Included in an array
notIn	Not included in an array
contains	Contains, case sensitive
notContains	Does not contain, case sensitive
containsi	Contains, case insensitive
notContainsi	Does not contain, case insensitive
null	Is null
notNull	Is not null
between	Is between
startsWith	Starts with
endsWith	Ends with
and	Logical and
or	Logical or
not	Logical not

Example query with filters

{
  documents(filters: { name: { eq: "test" }, or: [{ price: { gt: 10 }}, { title: { startsWith: "Book" }}] }) {
    data {
      id
    }
  }
}

Sorting

Queries can accept a sort parameter with the following syntax:

• to sort based on a single value: sort: "value"
• to sort based on multiple values: sort: ["value1", "value2"]

The sorting order can be defined with :asc (ascending order, default, can be omitted) or :desc (for descending order).

Example request: Sorting on title by ascending order

{
  documents(sort: "title") {
    data {
      id
    }
  }
}

Example request: Sorting on title by descending order

{
  documents(sort: "title:desc") {
    data {
      id
    }
  }
}

Example request: Sorting on title by ascending order, then on price by descending order

{
  documents(sort: ["title:asc", "price:desc"]) {
    data {
      id
    }
  }
}

Pagination

Queries can accept a pagination parameter. Results can be paginated either by page or by offset.

✏️ Note

Pagination methods can not be mixed. Always use either page with pageSize or start with limit.

Pagination by page

Parameter	Description	Default
pagination[page]	Page number	1
pagination[pageSize]	Page size	10

Example query: Pagination by page

{
  documents(pagination: { page: 1, pageSize: 10 }) {
    data {
      id
    }
    meta {
      pagination {
        page
        pageSize
        pageCount
        total
      }
    }
  }
}

Pagination by offset

Parameter	Description	Default	Maximum
pagination[start]	Start value	0	-
pagination[limit]	Number of entities to return	10	-1

Example query: Pagination by offset

{
  documents(pagination: { start: 20, limit: 30 }) {
    data {
      id
    }
    meta {
      pagination {
        start
        limit
      }
    }
  }
}

💡 Tip

The default and maximum values for pagination[limit] can be configured in the ./config/plugins.js file with the graphql.config.defaultLimit and graphql.config.maxLimit keys.