GraphQL + Serverless + Lamda

REST APIs have long been the industry standards and will prevail to be so for a while but with GraphQL as an alternative for web-developers to build APIs quickly and efficiently with serverless seeming to be taking away the last bit of configurations related mess, it’s becoming the first choice of many.

This article is assuming the you have basic knowledge on how to create API Gateway and Lambda function in AWS, that you know about basic GraphQL constructs like query and mutations.

GraphQL server uses the good old HTTP client-server protocol to transfer data. Usually HTTP is associated with REST in which entities are identified by “resources”. GraphQL server, on the other hand, operates on a single URL (we will be using /graphql) and all request goto the same URL path.

Reference: https://graphql.org/learn/serving-over-http/

With the above knowledge, we will be configuring API Gateway endpoints for both GET (query) and POST (mutations) for single path in our serverless config file.

For setting up a graphQL API using Lambda and API Gateway using serverless, we first need to install serverless using npm.

# Installing the serverless cli 
npm install -g serverless

Serverless has also given a bunch of instructions on how to install and setup the environment to get you started.

Serverless Getting Started Guide

Once the library is installed, create a project folder for writing lambda functions. Run the command below to create a boilerplate service with a service file named “post”. This will also create a file serverless.yml where the API related configurations will be specified and another file called handler.js.

serverless create --template aws-nodejs --path post-service --name post

Let’s take a look at the serverless.yml file first. You can specify the service name to be deployed, node version for Lambda to be used, Lambda memory size, timeout and such using the config fields given below. You can also refer to the Serverless website for a detailed explanation of each config. As I mentioned above, we will configure the path /graphql for both GET and POST below. We add another property “cors” as true to make sure the API gateway is configured to send CORS header with the response.

service: post-api # NOTE: update this with your service name

provider:
  name: aws
  runtime: nodejs6.10
  memorySize: 1024 # optional, in MB, default is 512
  timeout: 30 # optional, in seconds, default is 6

# you can overwrite defaults here
  stage: dev
  region: us-west-2
  profile: serverless
  role: ${file(../config.json):ROLE}

# you can define service wide environment variables here
  environment:
    NODE_ENV: ${file(../config.json):NODE_ENV}
   
# you can add packaging information here
package:
  include:
    - node_modules

functions:
  graphQLAPI:
      handler: lambdaHandler.handler
      events:
      - http:
          path: graphql
          method: get
          cors: true
      - http:
          path: graphql
          method: post
          cors: true

Modify the handler function to create a Lambda function for our express app. We will be using aws-serverless-express node package for this purpose. Copy the code below into the handler function.

const awsServerlessExpress = require('aws-serverless-express');
const app = require('./app');

const server = awsServerlessExpress.createServer(app);

exports.handler = (event, context) => awsServerlessExpress.proxy(server, event, context);

Now, create a file named app.js in which graphQL server is setup for the app to use it. GraphQL offers a UI tool, GraphiQL, which is very useful when developing and debugging APIs. When in development mode — process.env.NODE_ENV === ‘development’ config will let the GraphiQL tool open in the browser.

const express = require('express');
const body_parser = require('body-parser');
const cors = require('cors');
const graphqlHTTP = require('express-graphql');
const app = express();

app.use(body_parser.json({limit: '50mb'}));
app.use(cors());
app.use('/graphql', graphqlHTTP({
  schema: MyGraphQLSchema,
  graphiql: process.env.NODE_ENV === 'development',
}));

module.exports = app;

Now our app is complete. To deploy it, use the below command. Serverless uses CloudFormation stack to deploy/update the app.

serverless deploy