docs: graphql
This commit is contained in:
James
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: GraphQL Overview
|
||||
label: Overview
|
||||
order: 10
|
||||
---
|
||||
|
||||
Go over GraphQL configuration options.
|
||||
|
||||
- Naming conventions
|
||||
- List of all queries and mutations w/ examples
|
||||
- Context
|
||||
@@ -4,4 +4,65 @@ label: Custom Queries and Mutations
|
||||
order: 20
|
||||
---
|
||||
|
||||
Talk about how to add your own queries and mutations.
|
||||
You can add your own GraphQL queries and mutations to Payload, making use of all the types that Payload has defined for you.
|
||||
|
||||
To do so, add your queries and mutations to the main Payload config as follows:
|
||||
|
||||
| Config Path | Description |
|
||||
| -------------------- | -------------|
|
||||
| `graphQL.queries` | Function that returns an object containing keys to custom GraphQL queries |
|
||||
| `graphQL.mutations` | Function that returns an object containing keys to custom GraphQL mutations |
|
||||
|
||||
The above properties each receive a function that is defined with the following arguments:
|
||||
|
||||
**`GraphQL`**
|
||||
|
||||
This is Payload's GraphQL dependency. You should not install your own copy of GraphQL as a dependency due to underlying restrictions based on how GraphQL works. Instead, you can use the Payload-provided copy via this argument.
|
||||
|
||||
**`payload`**
|
||||
|
||||
This is a copy of the currently running Payload instance, which provides you with existing GraphQL types for all of your Collections and Globals - among other things.
|
||||
|
||||
##### Return value
|
||||
|
||||
Both `graphQL.queries` and `graphQL.mutations` functions should return an object with properties equal to your newly written GraphQL queries and mutations.
|
||||
|
||||
### Example
|
||||
|
||||
`payload.config.js`:
|
||||
|
||||
```js
|
||||
import { buildConfig } from 'payload/config';
|
||||
import myCustomQueryResolver from './graphQL/resolvers/myCustomQueryResolver';
|
||||
|
||||
export default buildConfig({
|
||||
serverURL: 'http://localhost:3000',
|
||||
graphQL: {
|
||||
// highlight-start
|
||||
queries: (GraphQL, payload) => {
|
||||
return {
|
||||
MyCustomQuery: {
|
||||
type: new GraphQL.GraphQLObjectType({
|
||||
name: 'MyCustomQuery',
|
||||
fields: {
|
||||
text: {
|
||||
type: GraphQL.GraphQLString,
|
||||
},
|
||||
someNumberField: {
|
||||
type: GraphQL.GraphQLFloat,
|
||||
},
|
||||
},
|
||||
args: {
|
||||
argNameHere: {
|
||||
type: new GraphQL.GraphQLNonNull(GraphQLString),
|
||||
}
|
||||
},
|
||||
resolve: myCustomQueryResolver,
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
// highlight-end
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
93
docs/GraphQL/overview.mdx
Normal file
93
docs/GraphQL/overview.mdx
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: GraphQL Overview
|
||||
label: Overview
|
||||
order: 10
|
||||
---
|
||||
|
||||
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 format 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:
|
||||
|
||||
```js
|
||||
const Post = {
|
||||
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 Name | Operation |
|
||||
| ---------------------- | -------------|
|
||||
| **`PublicUser`** | `findByID` |
|
||||
| **`PublicUsers`** | `find` |
|
||||
| **`mePublicUser`** | `me` auth operation |
|
||||
|
||||
**And the following mutations:**
|
||||
|
||||
| Query Name | Operation |
|
||||
| ------------------------------ | -------------|
|
||||
| **`createPublicUser`** | `create` |
|
||||
| **`updatePublicUser`** | `update` |
|
||||
| **`deletePublicUser`** | `delete` |
|
||||
| **`forgotPasswordPublicUser`** | `forgotPassword` auth operation |
|
||||
| **`resetPasswordPublicUser`** | `resetPassword` auth operation |
|
||||
| **`unlockPublicUser`** | `unlock` auth operation |
|
||||
| **`verifyPublicUser`** | `verify` auth operation |
|
||||
| **`loginPublicUser`** | `login` auth operation |
|
||||
| **`logoutPublicUser`** | `logout` auth operation |
|
||||
| **`refreshTokenPublicUser`** | `refresh` auth operation |
|
||||
|
||||
### Globals
|
||||
|
||||
Globals are also fully supported. For example:
|
||||
|
||||
```js
|
||||
const Header = {
|
||||
slug: 'header',
|
||||
label: 'Header',
|
||||
fields: [
|
||||
...
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
**Payload will open the following query:**
|
||||
|
||||
| Query Name | Operation |
|
||||
| ---------------------- | -------------|
|
||||
| **`Header`** | `findOne` |
|
||||
|
||||
**And the following mutation:**
|
||||
|
||||
| Query Name | Operation |
|
||||
| ---------------------- | -------------|
|
||||
| **`updateHeader`** | `update` |
|
||||
|
||||
### 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` mutation to use the Playground as an authenticated user.
|
||||
|
||||
<Banner type="success">
|
||||
<strong>Tip:</strong><br/>
|
||||
To see more regarding how the above queries and mutations are used, visit your GraphQL playground (by default at <a href="http://localhost:3000/api/graphql-playground">(http://localhost:3000/api/graphql-playground)</a> while your server is running. There, you can use the "Schema" and "Docs" buttons on the right to see a ton of detail about how GraphQL operates within Payload.
|
||||
</Banner>
|
||||
|
||||
### 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](/docs/production/security#graphql-complexity).
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: Using the GraphQL Playground
|
||||
label: Playground
|
||||
order: 30
|
||||
---
|
||||
|
||||
Talk about the GraphQL Playground
|
||||
|
||||
Talk about how to enable / disable it in production
|
||||
|
||||
Talk about how to log in
|
||||
Reference in New Issue
Block a user