GraphQL facade for REST API with AWS Lambda

5 min readDec 10, 2020

What exactly are we doing here?

We are going to create a GraphQL schema, This will wrap calls to an existing REST API. This schema will receive and resolve GraphQL queries all on the client-side.

The main benefit of this is, instead of having multiple endpoints for accessing your data you can focus on one and let the query determine what is returned.

Our GraphQL schema will act as a facade layer, Facade is just a fancy way of saying ‘it is simplifying our existing REST API’.

I have prepared a boilerplate repo for reference Here.

What is a REST API?

A RESTful API is an architectural style for an application program interface (API) that uses HTTP requests to access and use data. That data can be used to GET, PUT, POST, and DELETE data types, which refers to the reading, updating, creating, and deleting operations concerning resources.

Check here for a great explanation.

What is GraphQL?

GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data. GraphQL isn’t tied to any specific database or storage engine and is instead backed by your existing code and data.

Check here for a great explanation.

Setting up the serverless project

The boilerplate for this project was created using Serverless.
For a guide on how to get set up look here.

If you would just like to get a GraphQL instance set up locally you can ignore the serverless step and start the project using node server, this will start everything up using Node, Express & GraphQL.

Our existing REST API

To not pollute this post with unnecessary complications we will be using a static JSON file to mock out our REST API response.

Anytime a call would be made to an endpoint in a resolver we will simply return the relevant JSON response.

Resolvers, Schema & Types

For queries and mutations in GraphQL you need to implement Resolvers, Schema & Types, here is a brief breakdown of each.

Here is a great resource for GraphQL information.

Resolvers:

A resolver is a collection of functions that generate a response for a GraphQL query. In simple terms, a resolver acts as a GraphQL query handler.

Schema:

A GraphQL schema is at the core of any GraphQL server implementation. It describes the functionality available to the client applications that connect to it.

Types:

GraphQL is a strongly typed language. Type System defines various data types that can be used in a GraphQL application. The type system helps to define the schema, which is a contract between client and server.

What is a GraphQL Query?

A GraphQL operation can either be a read or a write operation. A GraphQL query is used to read or fetch values while a mutation is used to write or post values. In either case, the operation is a simple string that a GraphQL server can parse and respond to with data in a specific format. The popular response format that is usually used for mobile and web applications is JSON.

What is a GraphQL Mutation?

Mutation queries modify data in the data store and return a value. It can be used to insert, update, or delete data. Mutations are defined as a part of the schema.

What is GrapiQL?

GraphiQL is the GraphQL integrated development environment (IDE), it allows us to run all of our queries and mutations and test everything is working as expected.

To access GraphiQL for this project you simply need to go to the root /.

Once there you will see the interface, The left-hand side is for inputting your query/mutation, The right-hand side is where the results/errors will display.

In the readme of the boilerplate, I have given you example queries to use in GraphiQL.

Query example:

{ posts{  _id,  title,  subtitle }}

Mutation Example:

mutation { addPost(    title: "Brand New Post",    subtitle: "This is super interesting",    text: "The body for the new blog post" ) {    title    subtitle    text }}

Putting it all together

We will make a project that can be run locally on a Node server or from an AWS Lamda instance. 🚀

Before you begin to follow along make sure you have Node installed.

I created a boilerplate repo to accompany this post Here.

To run the boilerplate simply follow these 3 steps:

clone the repo
install dependencies (yarn or npm install)
run: node server

Once it is up and running head to the URL and you will be presented with GraphiQL.

Here is a bit of an explanation of the main pieces of this project.

Node setup:

To get our Node instance running we only need two files:

server.js

See here, This file is a basic file for starting our Node application.

app.js

See here, This sets up our express server and our GraphQL endpoint.

Interesting to note in the below block, graphiql: true Allows us to use the GraphiQL tool mentioned above.

app.use( ‘/’, graphqlHTTP({ 
    graphiql: true, 
    schema: GraphQLSchema
}));

Lambda setup:

If you are only interested in getting this running in Node you can skip this.

However, if you would like to get this running on AWS then you will need to create a serverless.yml file and the corresponding handler function.

Serverless.yml

See here, This file sets up everything you need with AWS API Gateway, enabling the endpoints for using GraphiQL in AWS.

This is the block that handles the creation of the routes, The great part about this is it saves you having to log in and manually create the routes.

functions:  
    getPosts:    
        handler: lambda.handler    
        events: 
          - http:          
               path: posts          
               method: get          
               cors: true      
          - http:          
               path: posts          
               method: post          
               cors: true

lambda.js

See here, The handler function will be triggered when our API Gateway routes are invoked.

We are using the npm package ‘aws-serverless-express’, This allows us to Run serverless applications and REST APIs using our existing Node.js application framework, on top of AWS Lambda and Amazon API Gateway.

GraphQL setup:

Everything you need for the GraphQL schema set up can be found in this directory.

We have our queries, resolvers, types, and mutations separated into separate directories.

schema.js

See here, Our schema js file is the heart of our GraphQL setup, here we specify our queries and mutations that we have configured.

Our Query (see here) is linked to our resolver (see here), This is where you would make your API call to retrieve data, in this example, I am returning a static JSON object to simulate data coming back from an API.

You will notice in our Query that we reference our type (see here), This assures that the data we are returned is exactly what we expect, allowing GraphQL to work its magic and work as expected.

Our Mutation (see here) Lists out the payload it expects to receive along with the types of data expected. If a sufficient payload is passed it will make it into the resolve function.

The resolve function is where you would fire off the payload to your API for insertion or update, then return the mutated response. For this example, we will just be returned the args that we sent.

Wrapping up:

I hope this helped to demystify how to implement GraphQL.

As mentioned above clone the boilerplate and get started.