♪ 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.
