Create an AWS CDK AppSync GraphQL API
There are only a few steps you have to take to create a live GraphQL API with AWS CDK's AppSync package.
First, define a GraphQL schema. This is where you define the data you want to query and create query and mutation functions.
Then, AppSync is used to create a new GraphQL API, passing in the schema you just created. When you deploy, an API key will be generated. You will need this key to interact with the API.
Tomasz Łakomy: [0:00] Every GraphQL API project starts with a schema. In order to create a schema, let me create a folder called GraphQL. Inside of it, I'm going to create a file called schema.graphql. To create a schema for our bookstore app, let's start with a type for a book. Each book is going to have an ID, which is going to be of type, ID. Each book is going to have a title, which is of type, string.
[0:22] Next, we're going to be able to mark whether we have completed a book or not. This is going to be a Boolean. We're going to also have a rating, which is of type, int. We're going to also have reviews, and reviews are going to be an array of strings.
[0:36] Note, that each book has to have an ID and a title, but the flag specifying whether we have completed the book, its rating, and its reviews, are completely optional. Apart from developer-specified types, GraphQL also has support for special types, including queries and mutations. In GraphQL, queries allows us to query the data, and mutation -- you've guessed it -- allows us to mutate the data.
[1:01] As such, I'm going to add a type Query. Inside of it, I'm going to specify a listBooks query. This is going to return an array of Books. Note that there are no exclamation marks here because we can have an empty list of books. Then, this query, the listBooks query, would simply return a null.
[1:19] For now, let's leave the schema and go back to our stack. First of all, in order to create an AppSync API, we have to install the AppSync construct for CDK. I'm going to open up my terminal and run npm install @aws-cdk/aws-appsync. Next, let's import it. I'm going to import everything as appsync from "@aws-cdk/aws-appsync".
[1:40] In order to create an AppSync API, I'm going to create a variable called API. I'm going to assign it to new appsync.GraphqlAPI. Every CDK construct takes three arguments. The first one is the scope which is usually this. Second one is the ID. I'm going to just call it "MyAPI". The third one are the props.
[1:59] In that case, the only thing that the AppSync API requires is the name. I'm going to call it "My Book API". I'm going to also assign it a GraphQL schema. This is going to be a GraphQL schema appsync.Schema. I'm going to take it fromAsset("graphql/schema.graphql").
[2:18] This is enough in order to create an AppSync API which is powered by this GraphQL schema that we have just created. Before we deploy the stack, let us run cdk diff to understand what exactly are we about to deploy.
[2:31] This stack is going to deploy three things. It's going to deploy our GraphQL API. It's also going to deploy an instance of an AppSync GraphQL schema. Also, it's going to assign a default API key so that we are able to call this API.
[2:45] With that, let me clear the terminal and run CDK deploy in order to deploy all of that into AWS. The deployment was successful. Let me go back to CloudFormation console and click on the Resources tab again. We can see that all of three resources that were listed by cdk diff command have been successfully deployed.
[3:05] Right now, I can go to AppSync console to see this API that we have just created. We can see this API over here. I'm going to click on this title to navigate through it and click on the Schema. Here, we can see the schema that we have created in our project that has been successfully deployed to AWS.
[3:23] The best part of building an API is being able to call it. To do that, click on Settings in order to copy the path to our API. We can see that over here. Next up, I'm going to navigate to GraphQL Playground. Honestly, any GraphQL client is good for that. I just happen to use GraphQL Playground.
[3:42] I'm going to paste this endpoint over here and click on OPEN. Whoops. We have a problem. I'm seeing a 401 error, which means that I don't have access to this API. That is by design. In order to use a AppSynch API, by default, we have to specify an API key. We can see that a default API key was created for us by CDK.
[4:04] I can just copy that over here, go back to my client. I'm going to specify an HTTP header. Let me zoom in a bit. I'm going to create a "x-api-key". I'm going to paste the API key for our API. This is better. I can click on the Schema tab now in order to see the GraphQL schema of our API so we can see the type Book over here.
[4:25] Let me test that. I'm going to do a query of listBooks. Inside of it, I'm going to call listBooks. I'm going to try to get the ID and a title of a book. When I hit Play, we can see that the API works fine, but I am not getting any books, which makes sense because we don't have any books yet.