strapi/website/documentation/concepts/graphql.md

GraphQL

Strapi build your GraphQL schema based on your model definitions. By default, you can make queries to the GraphQL server at http://localhost:1337/graphql.

Configuration

Configuration:

• Key: graphql
• Environment: all
• Location: ./config/general.json
• Type: object

Example:

{
  "graphql": {
    "route": "/graphql",
    "enabled": true,
    "graphiql": true,
    "pretty": true,
    "usefulQueries": true
  }
}

Options:

• route (string): The default locale to use.
• enabled (boolean): Enabled or disabled GraphQL.
• graphiql (boolean): Enabled or disabled GraphiQL, the graphical interactive in-browser GraphQL IDE developed by Facebook. The UI is accessible at http://localhost:1337/graphql in your browser.
• pretty (boolean): JSON response will be pretty-printed.
• usefulQueries (boolean): Enabled or disabled useful GraphQL queries. This configuration enables some useful queries for GraphQL. For example, if you have an API called User, you will be allowed to access to new queries such as getLatestUsers, getFirstUsers and countUsers. In the near future, we will add a start and end parameter in the query to filters results between two dates.

Queries

We recommend you to use GET requests to query your GraphQL server. By default, you can make a query to the GraphQL server at http://localhost:1337/graphql?query={...}.

Get latest records

• Query: getLatest[Model]s *(count: Int!)*

For example, this will return the five latest users:

{
  getLatestUsers(count: 5)
}

Get first records

• Query: getFirst[Model]s *(count: Int!)*

For example, this will return the eight first users:

{
  getFirstUsers(count: 8)
}

Get count of records

• Query: count[Model]

For example, this will return the numbers of users:

{
  countUsers
}

Mutations

The GraphQL implementation comes with basics mutations. This allows you to create, update or delete a record in your database.

We recommend you to use POST requests to query your GraphQL server for mutations. By default, you make a query to the GraphQL server at http://localhost:1337/graphql?query={...}. To send your data, you have to put them in your POST body request.

Create a record

• Mutation: create[Model]

For example, this will create a new user:

{
  mutation {
    createUser {
      id
      firstname
      lastname
    }
  }
}

In our request POST body, we have to send a JSON object:

{
  "firstname": "John",
  "lastname": "Doe",
  "age": "20",
  "address": "Sky.."
}

Update a record

• Mutation: update[Model] *(id: String!)*

For example, this will update an existing user with the id 1:

{
  mutation {
    updateUser(id:"1") {
      id
      firstname
      lastname
    }
  }
}

... in our request POST body, we have to sent this JSON object:

{
  "lastname": "Doe Junior",
}

!!! important Don't forget to send the ID in the body!

Delete a record

• Mutation: delete[Model] *(id: String!)*

For example, this will delete the user with the id 1:

{
  mutation {
    deleteUser(id:"1") {
      id
    }
  }
}

!!! note You have to specify field in your query. However the value will be null.

Permissions

Strapi allows you to apply policies on each query or mutation. During boot, Strapi will write (or rewrite) a configuration file called graphql.json in each API folder.

For example, the file looks like this in the /api/article/config/ folder:

{
  "query": {
    "article": [],
    "articles": [],
    "getLatestArticles": [],
    "getFirstArticles": [],
    "countArticles": []
  },
  "mutation": {
    "createArticle": [],
    "updateArticle": [],
    "deleteArticle": []
  }
}

Then, you can apply one or more policies on each query and mutation.

{
  "query": {
    "article": ["isConnected", "isOwner"],
    "articles": ["isConnected"],
    "getLatestArticles": ["isConnected"],
    "getFirstArticles": ["isConnected"],
    "countArticles": ["isConnected"]
  },
  "mutation": {
    "createArticle": ["isAuthorized", "isConnected"],
    "updateArticle": ["isAuthorized", "isConnected", "isOwner"],
    "deleteArticle": ["isAuthorized", "isConnected", "isOwner"]
  }
}

Use GraphQL in your codebase

You can make GraphQL query in your codebase. The graphql is exposed in global, and Strapi add a new function called query to easily make GraphQL query.

this.body = yield graphql.query("{articles{title}}", this);
// Don't forget to send the context. This is needed to apply permissions.

!!! note The policy doesn't need to be in the same API folder. The GraphQL permissions are based on the global strapi.policies variable which is an aggregate of the policies of the whole application. Also, the request is apply to the policies, in others words, this means you can handle sessions and cookies in the policy as usual.