Using aws apigateway with schemas

Question

Pulumi · Accepted Answer

When using AWS API Gateway with schemas, you often define a model that your API will use to serialize and deserialize data. This can be quite useful when you want to enforce the structure of the data being passed to and from your API endpoints, which in turn can help with data validation and documentation.

Models in API Gateway are defined using JSON Schema, which is a powerful way to describe your data structures. These models are associated with a REST API in API Gateway and can be referenced by methods in the API.

To illustrate how to use AWS API Gateway with schemas, we'll walk through an example of creating a REST API with a single resource and method. The method will reference a model schema for its request and response. We’ll use the AWS provider's `aws.apigateway.RestApi`, `aws.apigateway.Resource`, `aws.apigateway.Method`, and `aws.apigateway.Model` resources.

### Detailed Explanation

Here is the step-by-step breakdown of the process:

1. **`RestApi`** - This is the root entity of the API. It acts as a container for the resources, methods, and models of the API.
2. **`Resource`** - Represents a single resource within the API, such as `/users` or `/orders`.
3. **`Model`** - Defines the schema for the data. Models are used for input and output for methods within the API. The schema is defined using the JSON Schema format.
4. **`Method`** - Represents an HTTP method (GET, POST, PUT, DELETE, etc.) tied to a Resource and can reference Models for its request and response formats.

Now, let's create a TypeScript program using Pulumi to set up the API Gateway with a schema.

```typescript
import * as aws from "@pulumi/aws";

// Create a new API Gateway REST API
const api = new aws.apigateway.RestApi("MyApi", {
    description: "My REST API",
});

// Add a resource to the REST API. This represents a part of the API URL path.
const resource = new aws.apigateway.Resource("MyResource", {
    restApi: api.id,
    parentId: api.rootResourceId,
    pathPart: "myresource",
});

// Define the model's schema using JSON Schema format. This schema expects a simple JSON object with a `message` property.
const model = new aws.apigateway.Model("MyModel", {
    restApi: api.id,
    contentType: "application/json",
    schema: `{
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "ExampleModel",
        "type": "object",
        "properties": {
            "message": {"type": "string"}
        },
        "required": ["message"]
    }`,
});

// Create a method that references the model for both the request and the response.
const method = new aws.apigateway.Method("MyMethod", {
    restApi: api.id,
    resourceId: resource.id,
    httpMethod: "POST",
    authorization: "NONE",
    requestModels: {
        "application/json": model.name,
    },
});

// Stack export of the API URL for easy access
export const apiUrl = api.executionArn.apply(executionArn => `https://${executionArn}`);
```

In this program, we set up a simple REST API with a `POST` endpoint. The endpoint uses a simple model schema that requires a JSON payload with a `message` property of type string. This is a starting point for using AWS API Gateway with Pulumi and can be extended with more complex schemas, additional resources, and methods as needed.

Remember to install the necessary Pulumi and AWS SDK packages if you haven’t already:

```shell
npm install @pulumi/aws
```

Once the packages are installed and the program is ready, you can use the Pulumi CLI to create the resources in your AWS account.

Run the following commands to deploy your program:

```shell
pulumi up
```

This will prompt you for confirmation before creating resources in AWS. After confirmation, Pulumi will provision the API Gateway resources according to your program.

After deployment, you'll have a working API endpoint that you can integrate with other services or provide to your frontend applications.