GraphQL Server

GraphQL is a query language for APIs and a server-side runtime, open-sourced in 2015. It has snowballed in popularity, and big and small companies have adopted it to increase productivity.

In the article What is GraphQL? we describe the benefits of GraphQL for app and web developers. The following shortlist highlights some of the critical advantages of GraphQL:

• Single endpoint
• Less over-/under-fetching of data
• Strongly typed
• Client-side defines which data to return
• Real-time capabilities

To make all this work, a GraphQL server must do the heavy lifting and ensure that the fewest possible database lookups result in a satisfied client. The GraphQL server projects the results retrieved from the data source onto the specified query fields, validating and enforcing the defined query structure.

How a GraphQL server works

While not officially part of the spec, most GraphQL clients and servers use a defacto standard format for serving GraphQL over HTTP. Typically clients use HTTP POST requests with the following body structure:

{
  "query": "...",
  "operationName": "...",
  "variables": {
    "key": "value"
  }
}

The properties operationName and variables are optional fields. The operationName property is only required if multiple operations are present in the query.

The GraphQL standard suggests that clients should send queries and mutations separately. A GraphQL server should handle HTTP GET and POST requests. In a GET request, the client should pass the query as part of the URL query string with a parameter named query. In an HTTP POST request, the client sends a query or mutation through a JSON-encoded body.

Each time a GraphQL server receives a request, it goes through the following steps:

• Parsing the request-document
• Identifying operations (queries, mutations, or subscriptions)
• Validating input types, variables, and fields against the schema
• Running the operations by executing the attached resolvers

The GraphQL server executes queries in parallel while executing mutations sequentially to ensure no race conditions come up within one request. Although the specification doesn't specify how the server runs operations, it commonly traverses them field by field, executing the attached resolvers for each GraphQL field. This execution strategy might sound naive and can lead to performance penalties if the referenced data source doesn't support fetching in batches or does multiple fetches to a nested query which always yields the same result.

Running an Express GraphQL Server

While GraphQL APIs are easier to integrate for application developers, they can be challenging for the teams tasked with creating them. Initially, developers must decide whether to build a server from scratch or use one of the existing GraphQL services.

The quickest way to run a GraphQL server locally is using Express, a popular Node.js framework. Foremost, make sure that you have a recent Node version installed on your machine. The easiest way to install Node.js and manage different versions is by using the Node version manager.

With the express-graphql library, you can mount a GraphQL API server to the /graphql endpoint as follows:

var express = require('express');
var { graphqlHTTP } = require('express-graphql');
var { buildSchema } = require('graphql');

var schema = buildSchema("type Query { hello: String }");

// Resolver function for hello query field
var root = {
  hello: () => {
    return 'Hello world!';
  },
};

var app = express();
app.use('/graphql', graphqlHTTP({
  schema: schema,
  rootValue: root,
  graphiql: true,
}));

app.listen(4000);

If everything is set up, run the following commands in your terminal:

$ mkdir graphql-test    
$ npm init    
$ npm install express express-graphql graphql --save    
$ touch server.js    
$ vi server.js    
Copy & paste above code to server.js and save the file    
$ node server.js    
$ Open http://localhost:4000/graphql in a browser    
$ Run the { hello } query from the GraphiQL interface

While this little exercise was fun, the server only runs locally on your machine. So if you want to serve GraphQL requests from your app or web clients, you must get this server up and running somewhere in the cloud or on-prem.

Getting a GraphQL server production-ready can be a challenging mountain to climb if you don't have the experience. And we have yet to talk about user authentication and authorization, access control, managing data, provisioning servers, database migrations, and scaling infrastructure. Would it be nice if you got all of this out-of-the-box and could entirely focus on providing value to your customers?

Choosing a GraphQL Server

Searching for GraphQL services yields different results like:

• Hosted GraphQL
• Serverless GraphQL
• GraphQL-as-a-Service
• GraphQL backend builder
• Fully-managed GraphQL
• DIY GraphQL backend

They all indicate that large parts of the implementation process are automated, so you can focus on building value for customers instead of worrying about the upkeep of servers. With graphapi® we fully abstract the complexity of creating a GraphQL schema, provisioning servers, configuring data sources, and implementing resolvers. Developers can define object types and their relationships with a model-first approach.

Our mission is to empower teams to ship GraphQL-powered backends without requiring hand-written code. With graphapi®, you can get a fully managed GraphQL server with CMS capabilities ready in minutes.

Useful References

• GraphQL Express Server example