4.6 KiB
title |
---|
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 calledUser
, you will be allowed to access to new queries such asgetLatestUsers
,getFirstUsers
andcountUsers
. In the near future, we will add astart
andend
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",
}
Note: 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"]
}
}
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.