The stack
Introduction
From start to finish, this article should help you set up your first minimalist GraphQL API that runs on an AWS pipeline featuring API Gateway, AWS Lambda and DynamoDB for data storing. The boilerplate for this project is on Github!
You’ve probably heard about this new thing called GraphQL being the killer of REST based APIs, right? Well, today I’m going to show you how to set up a simple GraphQL API that runs on the cloud with minimal setup needed!
“Why the cloud?” you ask. By combining several AWS services, we can essentially make the API extremely simple and scaleable; no need to worry about the configuration of a server, or selecting which OS is best suited for running a server.
Then what are all these AWS services doing? Let’s have a quick look at what each of them does:
DynamoDB — This is a NoSQL document database. Basically, you have a table with some rows of data. Extremely simple, easy to set up and easy to query.
Amazon Lambda — Function as a service. You can run your own piece of code (in our example, the API) in the cloud while only paying for the milliseconds of computing power it used when calling that function.
API Gateway — Provides us with a URL for invoking our Lambda function. No need to manually configure an HTTP server; it’s all done automatically for you, and you only pay for the number of requests made to your API.
Any questions? Great, I would love to hear them. Comment down below if there’s something you don’t quite understand and I’ll try to help as best as I can :)
Note: This article assumes you already have NodeJS installed, an Amazon Web Services account, and that you at least know the basics of GraphQL. With that said, let’s get started!
Step 1:
Clone the git repo and run yarn install command at the root of the project to install the necessary Node dependencies.
Step 2: The Connection
Inside the dynamo.js file, be sure to set the right region on the object passed to AWS.config.update() method. Remember to change the region both on the endpoint url and the region string.
Authentication in this example is done through environment variables. For information on how to set them up and name them, check out the Amazon documentation.
Test the API locally by running
inside the /app folder. You can test the graphql by going to http://localhost:4000/graphql
After we have succesfully tested the API in a local environment, we need to select all of the project files and make a .zip package out of them. In the next step, we are going to upload the .zip package to AWS Lambda service. On to the Amazon Web Services!
Step 3: The Function
After signing in to the AWS Management console, go to the ‘Services’ tab and search for Lambda; you should be greeted with a page like this:
Click the ‘Create function’ button, and on the blueprint page, select ‘Author from scratch’, as we will not be using any existing templates.
Author from scratch!
We will create a trigger later, so for now, just click ‘Next’ on the ‘Configure triggers’ page:
Hit that ‘next’ button like it’s an ‘I’ve read the terms & conditions’ button!
Now you need to specify some basic information like the function’s name and runtime. For the runtime, choose Node.
Select ‘Upload a .ZIP file’ from the ‘Code entry’ type dropdown
The next step is just to upload the previously made .ZIP file!
Select ‘Create a custom role’
For the Lambda function role, select ‘Create a custom role’. A new tab should open up for creating a new role with the needed permissions.
Type a name for the role and then press the ‘Edit’ button.
Copy the JSON above and paste it into the field. Remember to replace the region and the account number on the Resource string with your region and account id!
If you do not know your amazon account id, check out the documentation.
Now click the ‘Allow’ button, and you should then be transported back to the Lambda functions configuration page. When ready, click that ‘Next’ button.
The final step is to review the Lambda function details. We should be good to go with our selections, so go ahead and create the function.
Yay! We have just succesfully created our first Lambda function! Th next step is to configure our API Gateway service to invoke our new Lambda function.
Step 4: The Gateway
Now we just connect our Lambda function to Amazon’s API Gateway! On Amazon’s ‘Services’ tab, find API Gateway, and press the ‘Create API’ button.
You should be greeted with a window that looks something like this:
Select the ‘New API’ radio button, and type in a name for your API!
After creating the API, we need to create a new resource through the ‘Actions’ dropdown. Create a new resource named ‘graphql’, like this:
After creating the ‘graphql’ resource, we need to create methods (GET and POST) to that resource. This is again done through the ‘Actions’ dropdown.
Create new method for the ‘graphql’ resource
You should now see a menu like this:
Setting up the methods for our resource
Check the ‘Use Lambda Proxy Integration’ checkbox, choose your region, and then type in your Lambda function’s name.
Then do this exact same procedure for the POST method!
Now you should be all done here! Just deploy the API from the ‘Actions’ dropdown.
(Almost) all done! just hit ‘Deploy API’!
The last dialogue before the API goes public! Select ‘[New Stage]’ as ‘Deployment stage’ and give it a name (could be anything).
Add a new deployment stage
After deploying, you should see your API Invoke URL. It looks something like this:
Open the link in a new window, and add our previously specified ‘/graphql’ resource name to the end of the URL, like so:
If everything goes as it should, you should see UI like this when you visit the API URL:
If everything works correctly, you can type in a query to get all of the records on the database like this:
The result should look something like this:
Note: When the table is first created, it takes about 20 seconds from the table creation to adding the initial data to the database. You might be faster than that when writing your first query, so don’t be alarmed if the API doesn’t return something straight away :)
Now you have an extremely simple GraphQL API running on a serverless pipeline!
If you liked this tutorial, be sure to press that ‘recommend’ button to spread the love ❤