Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

117 lines
4.4 KiB
Markdown
Raw Permalink Normal View History

2019-08-23 14:22:47 -07:00
---
title: "Serverless REST API"
2023-06-02 21:41:36 -07:00
title_tag: "Build a Serverless REST API"
meta_desc: "This tutorial will teach you how to build and deploy a Serverless REST API with DynamoDB on AWS that counts the number of times a route has hit."
aliases:
- /docs/quickstart/cloudfx/tutorial-rest-api/
- /docs/tutorials/cloudfx/rest-api/
2019-08-23 14:22:47 -07:00
---
2023-05-16 18:56:40 -07:00
With Pulumi, you can combine infrastructure definitions and application code in one program. The [@pulumi/cloud] library is a set of Pulumi [components](/docs/concepts/resources/components/) that provide a higher-level abstraction over AWS. So, instead of provisioning an API Gateway instance, Lambda functions, and setting up IAM roles, you can use [cloud.API] and define application code at the same time as the infrastructure it depends on.
2019-08-23 14:22:47 -07:00
In this tutorial, we'll show how to create a simple REST API that counts the number of times a route has been hit. To implement this API, we need a key-value store, an API endpoint, and a Lambda function.
{{< aws-js-prereqs >}}
## Create a simple REST API
1. Run `pulumi new`:
2019-08-23 14:22:47 -07:00
```bash
$ mkdir hello-http && cd hello-http
$ pulumi new aws-javascript
```
1. Replace the contents of `index.js` with the following:
2019-08-23 14:22:47 -07:00
```javascript
const cloud = require("@pulumi/cloud-aws");
// Create a mapping from 'route' to a count
let counterTable = new cloud.Table("counterTable", "route");
// Create an API endpoint
let endpoint = new cloud.API("hello-world");
endpoint.get("/{route+}", (req, res) => {
let route = req.params["route"];
console.log(`Getting count for '${route}'`);
// get previous value and increment
// reference outer `counterTable` object
counterTable.get({ route }).then(value => {
let count = (value && value.count) || 0;
counterTable.insert({ route, count: ++count }).then(() => {
res.status(200).json({ route, count });
console.log(`Got count ${count} for '${route}'`);
});
});
});
exports.endpoint = endpoint.publish().url;
```
The definition for `counterTable` stores a counter for each route, using [cloud.Table]. On AWS, this provisions a DynamoDB instance. To create a new API Gateway instance, we create an instance of [cloud.API]. New routes can be added to this endpoint using methods like `get`, `post`, `put` etc.
The function passed to `get` is the interesting part: this becomes the body of a new AWS Lambda function that is called on a GET request to the API Gateway. The body of this function can use variables defined in the main program, such as `counterTable`. This is translated to a lookup on the provisioned DynamoDB instance; there is no need to store its ARN in an environment variable.
1. Add and install the NPM dependencies:
2019-08-23 14:22:47 -07:00
```bash
$ npm install --save @pulumi/cloud @pulumi/cloud-aws
```
1. Preview and deploy changes via `pulumi up`:
2019-08-23 14:22:47 -07:00
```
$ pulumi up
Previewing update of stack 'hello-http'
...
Updating stack 'hello-http'
...
info: 14 changes performed:
+ 14 resources created
```
1. View the endpoint URL and curl a few routes:
2019-08-23 14:22:47 -07:00
```bash
$ pulumi stack output
Current stack outputs (1):
OUTPUT VALUE
endpoint https://5e8xrktey3.execute-api.us-west-2.amazonaws.com/stage/
$ curl $(pulumi stack output endpoint)/hello
{"route":"hello","count":1}
$ curl $(pulumi stack output endpoint)/woohoo
{"route":"woohoo","count":1}
```
1. To view the runtime logs of the Lambda function, use the `pulumi logs` command. To get a log stream, use `pulumi logs --follow`.
2019-08-23 14:22:47 -07:00
```
$ pulumi logs --follow
Collecting logs since 2018-05-01T21:22:59.000-07:00.
2018-05-01T22:25:05.040-07:00[ hello-world4fcc7b60] Getting count for 'hello'
2018-05-01T22:25:05.188-07:00[ hello-world4fcc7b60] Got count 1 for 'hello'
2018-05-01T22:25:13.562-07:00[ hello-world4fcc7b60] Getting count for 'woohoo'
2018-05-01T22:25:13.704-07:00[ hello-world4fcc7b60] Got count 1 for 'woohoo'
```
## Clean up
{{< cleanup >}}
## Next steps
For an end-to-end application with a frontend, see the [URL shortener sample](https://github.com/pulumi/examples/tree/master/cloud-ts-url-shortener).
<!-- LINKS -->
[@pulumi/cloud]: ./
[cloud.API]: /docs/reference/pkg/nodejs/pulumi/cloud/#API
[cloud.Table]: /docs/reference/pkg/nodejs/pulumi/cloud/#Table
2019-08-23 14:22:47 -07:00
<!-- END LINKS -->