mirror of https://gitee.com/bigwinds/arangodb
109 lines
3.8 KiB
Plaintext
109 lines
3.8 KiB
Plaintext
Using GraphQL in Foxx
|
|
=====================
|
|
|
|
`const createGraphQLRouter = require('@arangodb/foxx/graphql');`
|
|
|
|
Foxx bundles the [`graphql-sync` module](https://github.com/arangodb/graphql-sync), which is a synchronous wrapper for the official JavaScript GraphQL reference implementation, to allow writing GraphQL schemas directly inside Foxx.
|
|
|
|
Additionally the `@arangodb/foxx/graphql` lets you create routers for serving GraphQL requests, which closely mimicks the behaviour of the [`express-graphql` module](https://github.com/graphql/express-graphql).
|
|
|
|
For more information on `graphql-sync` see the [`graphql-js` API reference](http://graphql.org/docs/api-reference-graphql/) (note that `graphql-sync` always uses raw values instead of wrapping them in promises).
|
|
|
|
For an example of a GraphQL schema in Foxx that resolves fields using the database see [the GraphQL example service](https://github.com/arangodb-foxx/demo-graphql) (also available from the Foxx store).
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const graphql = require('graphql-sync');
|
|
const graphqlSchema = new graphql.GraphQLSchema({
|
|
// ...
|
|
});
|
|
|
|
// Mounting a graphql endpoint directly in a service:
|
|
module.context.use('/graphql', createGraphQLRouter({
|
|
schema: graphqlSchema,
|
|
graphiql: true
|
|
}));
|
|
|
|
// Or at the service's root URL:
|
|
module.context.use(createGraphQLRouter({
|
|
schema: graphqlSchema,
|
|
graphiql: true
|
|
}));
|
|
|
|
// Or inside an existing router:
|
|
router.get('/hello', function (req, res) {
|
|
res.write('Hello world!');
|
|
});
|
|
router.use('/graphql', createGraphQLRouter({
|
|
schema: graphqlSchema,
|
|
graphiql: true
|
|
}));
|
|
```
|
|
|
|
Creating a router
|
|
-----------------
|
|
|
|
`createGraphQLRouter(options): Router`
|
|
|
|
This returns a new router object with POST and GET routes for serving GraphQL requests.
|
|
|
|
**Arguments**
|
|
|
|
* **options**: `object`
|
|
|
|
An object with any of the following properties:
|
|
|
|
* **schema**: `GraphQLSchema`
|
|
|
|
A GraphQL Schema object from `graphql-sync`.
|
|
|
|
* **context**: `any` (optional)
|
|
|
|
The GraphQL context that will be passed to the `graphql()` function from `graphql-sync` to handle GraphQL queries.
|
|
|
|
* **rootValue**: `object` (optional)
|
|
|
|
The GraphQL root value that will be passed to the `graphql()` function from `graphql-sync` to handle GraphQL queries.
|
|
|
|
* **pretty**: `boolean` (Default: `false`)
|
|
|
|
If `true`, JSON responses will be pretty-printed.
|
|
|
|
* **formatError**: `Function` (optional)
|
|
|
|
A function that will be used to format errors produced by `graphql-sync`. If omitted, the `formatError` function from `graphql-sync` will be used instead.
|
|
|
|
* **validationRules**: `Array<any>` (optional)
|
|
|
|
Additional validation rules queries must satisfy in addition to those defined in the GraphQL spec.
|
|
|
|
* **graphiql**: `boolean` (Default: `false`)
|
|
|
|
If `true`, the [GraphiQL](https://github.com/graphql/graphiql) explorer will be served when loaded directly from a browser.
|
|
|
|
If a GraphQL Schema object is passed instead of an options object it will be interpreted as the *schema* option.
|
|
|
|
Generated routes
|
|
----------------
|
|
|
|
The router handles GET and POST requests to its root path and accepts the following parameters, which can be provided either as query parameters or as the POST request body:
|
|
|
|
* **query**: `string`
|
|
|
|
A GraphQL query that will be executed.
|
|
|
|
* **variables**: `object | string` (optional)
|
|
|
|
An object or a string containing a JSON object with runtime values to use for any GraphQL query variables.
|
|
|
|
* **operationName**: `string` (optional)
|
|
|
|
If the provided `query` contains multiple named operations, this specifies which operation should be executed.
|
|
|
|
* **raw**: `boolean` (Default: `false`)
|
|
|
|
Forces a JSON response even if *graphiql* is enabled and the request was made using a browser.
|
|
|
|
The POST request body can be provided as JSON or as query string using `application/x-www-form-urlencoded`. A request body passed as `application/graphql` will be interpreted as the `query` parameter.
|