GraphQL Overview

In addition to its REST and Local APIs, Payload ships with a fully featured and extensible GraphQL API.

By default, the GraphQL API is exposed via /api/graphql, but you can customize this URL via specifying your routes within the main Payload config.

The labels you provide for your Collections and Globals are used to name the GraphQL types that are created to correspond to your config. Special characters and spaces are removed.

Collections

Everything that can be done to a Collection via the REST or Local API can be done with GraphQL (outside of uploading files, which is REST-only). If you have a collection as follows:

const PublicUser = {
slug: 'public-users',
auth: true, // Auth is enabled
labels: {
singular: 'Public User',
plural: 'Public Users',
},
fields: [
...
],
}

Payload will automatically open up the following queries:

Query NameOperation
PublicUserfindByID
PublicUsersfind
mePublicUserme auth operation

And the following mutations:

Query NameOperation
createPublicUsercreate
updatePublicUserupdate
deletePublicUserdelete
forgotPasswordPublicUserforgotPassword auth operation
resetPasswordPublicUserresetPassword auth operation
unlockPublicUserunlock auth operation
verifyPublicUserverify auth operation
loginPublicUserlogin auth operation
logoutPublicUserlogout auth operation
refreshTokenPublicUserrefresh auth operation

Globals

Globals are also fully supported. For example:

const Header = {
slug: 'header',
fields: [
...
],
}

Payload will open the following query:

Query NameOperation
HeaderfindOne

And the following mutation:

Query NameOperation
updateHeaderupdate

Preferences

User preferences for the admin panel are also available to GraphQL. To query preferences you must supply an authorization token in the header and only the preferences of that user will be accessible and of the key argument.

Payload will open the following query:

Query NameOperation
PreferencefindOne

And the following mutations:

Query NameOperation
updatePreferenceupdate
deletePreferencedelete

GraphQL Playground

GraphQL Playground is enabled by default for development purposes, but disabled in production. You can enable it in production by passing graphQL.disablePlaygroundInProduction a false setting in the main Payload config.

You can even log in using the login[collection-singular-label-here] mutation to use the Playground as an authenticated user.

Query complexity limits

Payload comes with a built-in query complexity limiter to prevent bad people from trying to slow down your server by running massive queries. To learn more, click here.

Next

Adding your own Queries and Mutations