Repository files navigation

Create a GraphQL HTTP server with any HTTP web framework that supports connect styled middleware, includingConnect itself,Express andRestify.

npm install --save express-graphql

This module includes aTypeScriptdeclaration file to enable auto complete in compatible editors and typeinformation for TypeScript projects.

Just mountexpress-graphql as a route handler:

constexpress=require('express');const{ graphqlHTTP}=require('express-graphql');constapp=express();app.use('/graphql',graphqlHTTP({schema:MyGraphQLSchema,graphiql:true,}),);app.listen(4000);

Use.get or.post (or both) rather than.use to configure your route handler. If you want to show GraphiQL in the browser, setgraphiql: true on your.get handler.

constrestify=require('restify');const{ graphqlHTTP}=require('express-graphql');constapp=restify.createServer();app.post('/graphql',graphqlHTTP({schema:MyGraphQLSchema,graphiql:false,}),);app.get('/graphql',graphqlHTTP({schema:MyGraphQLSchema,graphiql:true,}),);app.listen(4000);

constexpress=require('express');const{ graphqlHTTP}=require('express-graphql');consttypeDefs=require('./schema');constresolvers=require('./resolvers');const{ makeExecutableSchema}=require('graphql-tools');constschema=makeExecutableSchema({typeDefs:typeDefs,resolvers:resolvers,});const{ execute, subscribe}=require('graphql');const{ createServer}=require('http');const{ SubscriptionServer}=require('subscriptions-transport-ws');constPORT=4000;varapp=express();app.use('/graphql',graphqlHTTP({schema:schema,graphiql:{subscriptionEndpoint:`ws://localhost:${PORT}/subscriptions`},}),);constws=createServer(app);ws.listen(PORT,()=>{// Set up the WebSocket for handling GraphQL subscriptions.newSubscriptionServer({      execute,      subscribe,      schema,},{server:ws,path:'/subscriptions',},);});

ThegraphqlHTTP function accepts the following options:

• schema: AGraphQLSchema instance fromGraphQL.js.Aschemamust be provided.

• graphiql: Iftrue, presentsGraphiQL when the GraphQL endpoint isloaded in a browser. We recommend that you setgraphiql totrue when yourapp is in development, because it's quite useful. You may or may not want itin production.Alternatively, instead oftrue you can pass in an options object:

  • defaultQuery: An optional GraphQL string to use when no queryis provided and no stored query exists from a previous session.Ifundefined is provided, GraphiQL will use its own default query.

  • headerEditorEnabled: An optional boolean which enables the header editor whentrue.Defaults tofalse.

  • subscriptionEndpoint: An optional GraphQL string contains the WebSocket server url for subscription.

• rootValue: A value to pass as therootValue to theexecute()function fromGraphQL.js/src/execute.js.

• context: A value to pass as thecontextValue to theexecute()function fromGraphQL.js/src/execute.js. Ifcontext is not provided, therequest object is passed as the context.

• pretty: Iftrue, any JSON response will be pretty-printed.

• extensions: An optional function for adding additional metadata to theGraphQL response as a key-value object. The result will be added to the"extensions" field in the resulting JSON. This is often a useful place toadd development time metadata such as the runtime of a query or the amountof resources consumed. This may be an async function. The function isgiven one object as an argument:{ document, variables, operationName, result, context }.

• validationRules: Optional additional validation rules that queries mustsatisfy in addition to those defined by the GraphQL spec.

• customValidateFn: An optional function which will be used to validateinstead of defaultvalidate fromgraphql-js.

• customExecuteFn: An optional function which will be used to executeinstead of defaultexecute fromgraphql-js.

• customFormatErrorFn: An optional function which will be used to format anyerrors produced by fulfilling a GraphQL operation. If no function isprovided, GraphQL's default spec-compliantformatError function will be used.

• customParseFn: An optional function which will be used to create a documentinstead of the defaultparse fromgraphql-js.

• formatError: is deprecated and replaced bycustomFormatErrorFn. It will beremoved in version 1.0.0.

In addition to an object defining each option, options can also be provided asa function (or async function) which returns this options object. This functionis provided the arguments(request, response, graphQLParams) and is calledafter the request has been parsed.

ThegraphQLParams is provided as the object{ query, variables, operationName, raw }.

app.use('/graphql',graphqlHTTP(async(request,response,graphQLParams)=>({schema:MyGraphQLSchema,rootValue:awaitsomeFunctionToGetRootValue(request),graphiql:true,})),);

Once installed at a path,express-graphql will accept requests withthe parameters:

• query: A string GraphQL document to be executed.

• variables: The runtime values to use for any GraphQL query variablesas a JSON object.

• operationName: If the providedquery contains multiple namedoperations, this specifies which operation should be executed. If notprovided, a 400 error will be returned if thequery contains multiplenamed operations.

• raw: If thegraphiql option is enabled and theraw parameter isprovided, raw JSON will always be returned instead of GraphiQL even whenloaded from a browser.

GraphQL will first look for each parameter in the query string of a URL:

/graphql?query=query+getUser($id:ID){user(id:$id){name}}&variables={"id":"4"}

If not found in the query string, it will look in the POST request body.

If a previous middleware has already parsed the POST body, therequest.bodyvalue will be used. Usemulter or a similar middleware to add supportformultipart/form-data content, which may be useful for GraphQL mutationsinvolving uploading files. See anexample using multer.

If the POST body has not yet been parsed,express-graphql will interpret itdepending on the providedContent-Type header.

• application/json: the POST body will be parsed as a JSONobject of parameters.

• application/x-www-form-urlencoded: the POST body will beparsed as a url-encoded string of key-value pairs.

• application/graphql: the POST body will be parsed as GraphQLquery string, which provides thequery parameter.

By default, the express request is passed as the GraphQLcontext.Since most express middleware operates by adding extra data to therequest object, this means you can use most express middleware just by inserting it beforegraphqlHTTP is mounted. This covers scenarios such as authenticating the user, handling file uploads, or mounting GraphQL on a dynamic endpoint.

This example usesexpress-session to provide GraphQL with the currently logged-in session.

constsession=require('express-session');const{ graphqlHTTP}=require('express-graphql');constapp=express();app.use(session({secret:'keyboard cat',cookie:{maxAge:60000}}));app.use('/graphql',graphqlHTTP({schema:MySessionAwareGraphQLSchema,graphiql:true,}),);

Then in your type definitions, you can access the request via the third "context" argument in yourresolve function:

newGraphQLObjectType({name:'MyType',fields:{myField:{type:GraphQLString,resolve(parentValue,args,request){// use `request.session` here},},},});

The GraphQL response allows for adding additional information in a response toa GraphQL query via a field in the response called"extensions". This is addedby providing anextensions function when usinggraphqlHTTP. The functionmust return a JSON-serializable Object.

When called, this is provided an argument which you can use to get informationabout the GraphQL request:

{ document, variables, operationName, result, context }

This example illustrates adding the amount of time consumed by running theprovided query, which could perhaps be used by your development tools.

const{ graphqlHTTP}=require('express-graphql');constapp=express();constextensions=({  document,  variables,  operationName,  result,  context,})=>{return{runTime:Date.now()-context.startTime,};};app.use('/graphql',graphqlHTTP((request)=>{return{schema:MyGraphQLSchema,context:{startTime:Date.now()},graphiql:true,      extensions,};}),);

When querying this endpoint, it would include this information in the result,for example:

{"data":{ ...},"extensions":{"runTime":135}}

GraphQL'svalidation phase checks the query to ensure that it can be successfully executed against the schema. ThevalidationRules option allows for additional rules to be run during this phase. Rules are applied to each node in an AST representing the query using the Visitor pattern.

A validation rule is a function which returns a visitor for one or more node Types. Below is an example of a validation preventing the specific field namemetadata from being queried. For more examples, see thespecifiedRules in thegraphql-js package.

import{GraphQLError}from'graphql';exportfunctionDisallowMetadataQueries(context){return{Field(node){constfieldName=node.name.value;if(fieldName==='metadata'){context.reportError(newGraphQLError(`Validation: Requesting the field${fieldName} is not allowed`,),);}},};}

Disabling introspection does not reflect best practices and does not necessarily make yourapplication any more secure. Nevertheless, disabling introspection is possible by utilizing theNoSchemaIntrospectionCustomRule provided by thegraphql-jspackage.

import{NoSchemaIntrospectionCustomRule}from'graphql';app.use('/graphql',graphqlHTTP((request)=>{return{schema:MyGraphQLSchema,validationRules:[NoSchemaIntrospectionCustomRule],};}),);

getGraphQLParams(request: Request): Promise<GraphQLParams>

Given an HTTP Request, this returns a Promise for the parameters relevant torunning a GraphQL request. This function is used internally to handle theincoming request, you may use it directly for building other similar services.

const{ getGraphQLParams}=require('express-graphql');getGraphQLParams(request).then((params)=>{// do something...});

During development, it's useful to get more information from errors, such asstack traces. Providing a function tocustomFormatErrorFn enables this:

customFormatErrorFn:(error)=>({message:error.message,locations:error.locations,stack:error.stack ?error.stack.split('\n') :[],path:error.path,});

Each release ofexpress-graphql will be accompanied by an experimental release containing support for the@defer and@stream directive proposal. We are hoping to get community feedback on these releases before the proposal is accepted into the GraphQL specification. You can use this experimental release ofexpress-graphql by adding the following to your project'spackage.json file.

"express-graphql": "experimental-stream-defer","graphql": "experimental-stream-defer"

Community feedback on this experimental release is much appreciated and can be provided on thePR for the defer-stream branch or theGraphQL.js issue for feedback.

This repository is managed by EasyCLA. Project participants must sign the freeGraphQL Specification Membership agreement before making a contribution. You only need to do this one time, and it can be signed byindividual contributors or theiremployers.

To initiate the signature process please open a PR against this repo. The EasyCLA bot will block the merge if we still need a membership agreement from you.

You can finddetailed information here. If you have issues, please emailoperations@graphql.org.

If your company benefits from GraphQL and you would like to provide essential financial support for the systems and people that power our community, please also consider membership in theGraphQL Foundation.