Building Real-time Serverless GraphQL APIs on AWS with TypeScript and CDK


CDK (Cloud development kit) enables developers to build cloud infrastructure using popular programming languages like Python, Typescript, or JavaScript. CDK is a next-level abstraction in infrastructure as code, allowing developers who were traditionally unfamiliar with cloud computing to build scalable APIs and web services using their existing skillset, and do so in only a few lines of code.

In this talk, you’ll learn how to use the TypeScript flavor of CDK to build a hyper-scalable real-time API with GraphQL, Lambda, DynamoDB, and AWS AppSync . At the end of the talk, I’ll live code an API from scratch in just a couple of minutes and then test out queries, mutations, and subscriptions.

By the end of the talk, you should have a good understanding of GraphQL, AppSync, and CDK and be ready to build an API in your next project using TypeScript and CDK.


♪ Okay. Hello, everyone. And thank you so much for attending my talk today. I'm really excited to be talking about this subject because it's something that I've been really using a lot lately and it's really powerful. So I'm going to be talking about building real-time serverless graphql APIs with typescript, AppSync, and cdk. My name is Nader Dabat. I'm a senior developer advocate, and I'm by trade a front-end and mobile developer, and I've just now been working with aws and back-end services for the last couple of years. And lately, I've really been focusing on building full-stack cloud and full-stack serverless apps. So let's go ahead and jump right in because we have a lot to cover. I'm going to be talking about a couple of things and they all kind of fit together. So we're going to first start off with an introduction to graphql. We're going to then talk about aws AppSync, a managed graphql service. We're going to then do a brief intro to cdk, and then we're going to kind of talk about how all this stuff fits together, AppSync, cdk, and graphql. And then I'm going to do a live coding demo, and I think the live coding demo kind of will show you how all this stuff works together better than any presentation will. But hopefully, putting all this together will be really helpful for you and you'll learn something. So let's talk about graphql for a bit. graphql, if you look it up on the internet and you find the definition, you might see something like this, a query language for your api. This doesn't say a whole lot. Let's dive a little bit deeper. With graphql, you have your almost like a menu of your data, which is your graphql schema. The schema has all of the different data types, which are basically types, and all of the operations against those types. So you have maybe a to-do app. You might think of something like a to-do type, and then you might have operations for creating, reading, updating, and deleting your to-dos. All of that is defined in your schema. And once you've deployed your api, and we're going to talk about that a little bit more in just a moment, you can then just ask for the data that you want. And this is kind of the thing you've probably heard about before if you've ever looked into graphql, is one of the really powerful things about it is you have the ability to build much lower latency and more, I guess, controlled APIs than when you're working with REST endpoints, because you have a lot more control about the data that is getting sent back and forth across the wire. And then you get your response data returned to you in JSON. So a graphql api is made up of three main parts. You have your schema, which we talked about just a second there. We'll dive into a little bit more in just a second. You have your resolvers, and then you have your data sources. So the schema is where all of your data declarations live. So again, for a to-do app, you might have a to-do type. And then to operate against that to-do type, you might need to define some operations. Here you might have a way to get a single to-do by ID. You might have a way to create a new to-do using a create to-do operation. And these are defined in queries, mutations, and then we also have a new type that is kind of unique to graphql called a subscription. We'll talk about all three of those in just a second. So once you've defined your schema, you then have your data sources. And the data sources are where the data is coming from for these operations. And then you're going to get the data returned to you in one of the types that you've defined in your schema. And the way that those operations are handled are done usually in a resolver. And the resolver are really essentially just a function or some type of code that maps the graphql operation to a data source. And this is an implementation detail for you as a developer. If you're building out your own api, this is going to be kind of up to you how you write this. A lot of the frameworks have a little bit more opinionated ways about doing this. And if you're working with a graphql as a service, something like AppSeq, those are also opinionated as well. So a data source can be either a database, a function that is kind of outside of the main service itself, or an HTTP endpoint for bringing in a microservice architecture into a graphql api. So let's talk about the data fetching piece of graphql, which is really interesting. With graphql, you might be coming at this from REST. So I think it's really convenient and really interesting to kind of compare the two, graphql versus REST. With graphql, you have this idea of queries, mutations, and subscriptions, and these map really well to things that we've done in the REST world, kind of mapping to things like the HTTP verbs that we work with. So when you need to read some data, like getting or listing a list of items, you're going to be using a graphql query. If you're going to be updating, creating, or deleting anything, you're going to be typically using a mutation. And then if you need some type of real-time aspect to your api, you're going to be using subscriptions. So let's take a look at a table of graphql versus REST verbs. So again, mapping a GET request might make a lot of sense to a graphql query. So getting an item by ID or getting a list of items will be typically a graphql query. And then POST, PUT, DELETE, or PATCH operations will be graphql mutations. So that being said, let's take a look at kind of the way that graphql just brings back the data that you've asked for, kind of like we mentioned just a moment ago. So in a query, you might be able to say, okay, we have this graphql type of TODO, and this TODO has four fields. It has an ID, a name, and a completed, and a created at value, or fields. And in this request, we want to get all four of those fields, so that's fine. But you can also say, I only want to get a subset or a smaller selection set of these fields. And this is going to continue to work. You don't have to kind of make any updates to your backend. The way that graphql is built, the way that these queries are created, you only get the data that you've asked for. So again, if you've ever worked with building out different types of client applications for a single backend, in the modern world, you might have a web, a mobile, a desktop app that also maybe has an Apple Watch app or even a car app. In the future, you never know. Having graphql as a data source allows you to kind of have a lot more control over your data access without having to change a lot of code on your backend once the implementation is complete. So next, let's talk about the graphql subscriptions, which are the real-time aspect of graphql. graphql subscriptions enable real-time communication between a client and an api. Subscriptions are event-based, so when you create, update, or delete an item, you might be able to subscribe to that event. So typically, a subscription might have a name like onCreate, onUpdate, or onDelete. So for a to-do app, you might have onCreateToDo, onUpdateToDo, et cetera. Subscriptions are typically a two-way connection, so you have to have a way to send the update and then have a way to receive the update back on the client. So a lot of times, you are then asked about, okay, with this being said, how do you actually implement graphql subscriptions? So if you're using a service like Hasura or AppSync or any of these graphql services, this is going to be kind of taken care of for you. But if you're building your own api, you're typically going to be making the decision between something like service and events or WebSockets. I think a lot of the time, you're seeing that graphql APIs are built using WebSockets. So again, very similar to like a graphql query where you're asking for the data that you'd like and you only get that data, you can also subscribe to only subsets of data. So even though our to-do type has four different fields, we can make subscriptions and only return back like a subset of those fields. So let's say we only are interested in the ID, the name, and the completed value, we'll create a subscription, we'll then only receive that data that we're subscribed to. So that's kind of a brief overview of graphql. Let's now talk about AppSync and then we're going to talk about cdk and then we're going to do a live demo. So AppSync is a managed graphql service and it's built using a lot of really scalable infrastructure on aws. So AppSync provides a consistent api layer for any aws service or any data source. And these data sources don't have to live on aws, they can pretty much live anywhere as long as they have some type of HTTP access or some type of access to your data center, which is kind of also available as well. We have enterprise security features built in. So if you need to have a single or multi-authorization types for a public and private access or a combination of the two, we have that built in. So IAM, we have OIDC for bringing your own authentication provider. So if you're using something like Auth0 or Okta, you use OIDC. We have Cognito for a managed authentication service and then we have api keys for public access. And one of the really interesting things about AppSync is how easy it is to add a graphql subscription. And we're going to kind of be walking through that in code in just a moment. But for any mutation, subscriptions are already built into the service. All you need to do is add one additional line of code and you can subscribe to any type, but also any subset of that type. So for instance, you might think of a chat app where you have messages. You can also pass in arguments, up to five different arguments to subscribe to only updates for something like a chat room using the chat room ID. And then we also build and maintain our own SDKs for all these aws services, including AppSync. So you can use something like Urql or apollo, but we have our own SDKs that manage a lot of things like authorization headers. And we have SDKs and libraries for web, iOS, Android, react Native, and Flutter. So let's talk about cdk for a moment. cdk is short for cloud Development Kit. And cdk is basically a new way to write infrastructure as code. And when I say new, it's kind of like a little over two years, so it's not that new, but it's still fairly new. And you can do this. It's a lot different than any of the infrastructure as code that we've seen in the past, because instead of using some type of configuration file, like a JSON or YAML, you're actually using typescript, javascript, Python, whatever your favorite programming language is. cdk first only supported aws, but now it supports other cloud providers, including azure. And it's really, really gaining a lot of popularity. And a lot of Amplify users that kind of build out their infrastructure use cdk as the cloud formation provider, or they might use a combination of Amplify and cdk, and then they use the Amplify client libraries to connect. So initializing a new cdk project looks something like this. You just have, you install the cdk CLI, and then you initialize a new project, and you're ready to go. And then you can start adding additional features from the boilerplate that's provided there. And we're going to kind of be starting off from a base project, and we're going to be looking at how that works. So AppSync with cdk. What you'll typically do is you'll go ahead and create your new cdk project, just like we showed you just a moment ago, cdk init. You'll install any npm packages that you'll need, any cdk packages using npm. So for instance, for AppSync, you're going to need to install the AppSync cdk package, and then you'll also maybe need to install other data sources like lambda, DynamoDB, for whatever databases you're interacting with from cdk. You'll then create and configure the api in code. So you'll give the api a name, you'll set your graphql schema, and then you'll set some base authorization configuration. And the api that we're going to build, we're going to be setting the base authorization configuration as public. You then add data sources, and then you add your resolvers to those data sources. So you might say, okay, I've created this api, I need to have a NoSQL database, I need a SQL database, and then I need to have a way to map my resolvers for the types and the fields and the operations of my schema to those data sources. And then you kind of define all this stuff really in code. And we're going to be working with typescript today. So I think the most interesting thing, though, like we talk a lot about this stuff, is the actual live demo because we're going to be starting from scratch, building this out. So what I'm going to do is I'm going to go into a project that I've created here. This is a really empty cdk app. I'm going to go ahead and open this up. And in the lib directory, we have the entry point for the cdk app. And this is basically going to be where we're writing our code. And if we go to package.json, we'll see that I've installed three dependencies, AppSync for cdk, DynamoDB, which is a NoSQL database, and aws lambda. So using all of these things, we're going to build out an api in just a couple of minutes. So what I'd like to do first is go ahead and get my imports. I'm going to import cdk, AppSync, DynamoDB, and lambda. And we're going to be using those to kind of create our api. Next, we're going to go ahead and create the api reference using the AppSync construct. And we're going to give the api a name. The api name is going to be cdk Notes AppSync api, and maybe we'll call this like react Summit or something like that. I'll give a location for the graphql schema. This is going to be in graphql.schema.graphql, which we'll create in just a moment. We then set a default authorization configuration, and for us, we're just going to be using api key, so we set that here. And then we give an expiration, and I'm setting that to expire 365 days from now. And then if you needed multiple authorization types, we could have done that here, but we're not. And then I'm setting x-ray enabled because x-ray is basically a really sophisticated logging system that we can use for additional logging for debugging purposes. The next thing we want to do is go ahead and create our graphql schema, so I'm going to go ahead and create a folder here and a schema.graphql. And here we're going to go ahead and create our schema. And the schema that we're going to create is for Notes app. So we have a note type. We have a query for listing notes. We have a mutation for creating notes, and then we have the real-time piece, which is the subscription here for onCreateNote. So we're going to say we want to then have our at underscore, I'm sorry, at aws underscore subscribe directive attached to this. And this is what adds the real-time functionality. So if we look at this schema and we delete this, this is kind of all just basic graphql. This directive here is kind of AppSync specific, but this is all you need to attach to any subscription to go ahead and set an array of mutations for the subscription to fire. No additional code is needed. So we're going to say we want to pass in an array, but the only item we're interested in is creating a note. We want to subscribe to that event, and then we're going to have this onCreateNote subscription created for us. So I'm going to go ahead and close that. And what we want to do now is go ahead and create a lambda function. And the lambda function is going to be where our business logic or our logic for interacting with the database lives. So we're going to go ahead and say we're creating a lambda function. We're referencing that as notes lambda. We're saying new lambda function. And I might minimize this over here to kind of get a better look at the code. We're setting a run time. The run time is node.js. We're giving a location for our code, which is this lambda functions folder, and then an entry point, which is main.handler. And then we're setting memory size, bumping that up a little bit to make this more performant. And then what we're doing is we're taking that api reference. So we created our api up here. And we're saying we want to do an add lambda data source, and then we're passing in this notes lambda right here. So we create the api. We're setting a lambda data source. Now we need to go ahead and create that lambda function code. So what we're going to do is let's go ahead and create a new folder called lambda-FNS. And then that's where our lambda code is going to live in just a moment. But for now, let's continue on. And what we want to do is we want to add our resolvers. And we need two resolvers because in our graphql schema, we have two operations. We have a query and we have a mutation. The query is for list notes. So we're basically saying we want to resolve the list notes query into this function. So when this query is called, we're just passing that into the lambda function and the event. The same thing goes for the mutation. When a new note is created, when the create note resolver is fired, it's going to be passing the event into the lambda function. And then finally, what we need is some type of database to work with. So we're going to create a DynamoDB table. The DynamoDB table is going to be where we store all of our data. So I'm creating a new table called notes table using the DynamoDB cdk construct. We're setting some basic configuration, setting this to be serverless by using pay per request. And we're setting a partition key, which is basically the primary key of ID. And then we're going to go ahead and grant access to the DynamoDB table from our lambda function, basically saying, okay, this function can interact with this table. And then we're calling the add environment function, where we're setting environment variable by calling notes lambda dot add environment. And what we're doing is basically saying, okay, we want to be able to access an environment variable called notes table, but we don't know the actual value of that yet. So we're just going to kind of set the environment variable there because we don't know the value of the actual table name. But we know we need to access that table. This way in the lambda function, we can reference process dot env dot notes table. So basically we create the api. We created a function. We mapped the operations from our api into that function. And then we created a database table and enabled access from our lambda function to that table. We did all of that. And really, if we minimize this, it would be something like 40 lines of code or something or less. So now that all that is created, we're really done with our, you know, our code on our actual cdk project. Now all we need to do is create our lambda functions. So I'm going to have a note dot TS file. And here we're going to have our note type. This is just going to map pretty closely to our graphql type. We're just going to be using this for our typescript and our here. And what we want to do now is have a main dot JS. Oops, this actually needs to be typescript, so I'm going to rename that to TS. In this function, we're going to have our two operations that we're going to be importing and using in just a moment. One for creating a note against DynamoDB, one for listing notes. We have a type that we're creating that has a couple of different fields. One is the info object that has the field name and one is the arguments object that has the notes. And we're going to be basically using these two pieces of data, I guess you could say, coming off of the event that's coming into the lambda function. So when this function is invoked, the event is going to have an event dot info object. It's going to have an event dot arguments object. The arguments are the arguments passed into the function or into the operation. So create notes would have a notes argument. Get note by ID might have a note ID. And then the field name is the actual graphql query itself, or the graphql operation itself. So the field name is going to be referenced down here as create note or list notes. So we're going to be switching on that field name. So we're going to say, OK, if it's create note, we want to execute this function. If it's list notes, we want to execute that function. So with that being said, we need to go ahead and create those last two functions. So we have create note dot TS and we have list notes dot TS. This is a lambda function for interacting with DynamoDB. So we're basically creating a params object, taking the note out of the argument, and we're calling the document DynamoDB document client dot put, basically creating a new item. This is not really what we're focused on, though, but this is some pretty basic code for interacting with DynamoDB from a lambda function. And then the other operation is list notes. And this is a DynamoDB scan. So we're basically going to say the params we need is the only thing we need to know is the table name, which is coming off of the process environment variable. And we're calling the document client dot scan, passing in these params. And this is just going to pull everything out of that table and then return it back to us. So if I go back to my, you know, my cdk, you can notice that I have this main dot handler referenced here and then in the lambda functions folder. If we go to our lambda functions folder, we go to main. We see that the the main function here is called handler. So that's kind of how that's being referenced. And that's all we need to do. So let's go ahead and test this out. So I'm going to go ahead and say npm run build. And this is going to go ahead and build out all of that typescript into javascript, which is what the service needs to run. And then we're going to call cdk deploy. And then cdk deploy is going to actually now look at our cdk stack and it's going to say, oh, we need all this stuff to be deployed. We're ready to roll. All we have to do is say yes. And all of this infrastructure is code is going to be deployed. This is going to take maybe a couple of minutes. OK, so after the stack has been deployed, we can now go ahead and test this out. So I'm going to go into the aws console. And we're going to go to the api we just created by going to AppSync. And we're going to then look for the notes app. So we have the notes app here. We can now go into our queries and we can say mutation create note. And then we'll just go ahead and return the ID name. And I think we also have the completed value, which we'll go ahead and set here as false. And then finally, we'll just do a query of list notes. And here we should go ahead and see the notes being returned from our api. So our api is up and running. Finally, we'll set up a subscription. And the subscription is going to basically be returning the same field. So let's copy those. And for on create note, we want those. And now we have a subscription running. So if a new item is created, the subscription data would come through here. So that's really about it. I'm really excited about this stack because I get to use my front end skill set, typescript, javascript to kind of build out all this infrastructure as code. cdk is a really cool community. It's growing really fast. Works really well with Amplify. If you're interested in full stack cloud computing, check it out. Follow me on Twitter at Dabit3. Thank you for watching. This has been a presentation of the aws cloud Platform.
25 min
17 Jun, 2021

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

Workshops on related topic