Configuring base path mapping for API services

Question

Pulumi · Accepted Answer

Base path mapping in API Gateway is a feature that allows you to serve multiple APIs from a single domain name or base URL. Instead of exposing the raw API endpoint generated by API Gateway, you can map the API to a custom domain name and choose a base path that clients will use to access the API. This is useful for versioning, API management, and creating cleaner, more user-friendly URLs.

When you want to configure base path mapping for your API services, there are generally a few steps you need to take:

1. **Define your API Gateway**: You need to have an API Gateway created. It serves as the entrance to your APIs.
2. **Create a domain name**: The domain name is what your users will see and use to access your API.
3. **Setup the base path mapping**: This step involves connecting your custom domain name to your API Gateway, and selecting what base paths direct to what APIs.

In Pulumi, you accomplish this by using resources such as `Api`, `DomainName`, and `BasePathMapping`. The example below will guide you through the process of setting up base path mapping for an AWS API Gateway using Pulumi in TypeScript.

First, define your API Gateway and deploy an instance of it. Then, create a custom domain name and the base path mapping that routes requests to your API Gateway.

Here's the Pulumi program written in TypeScript that demonstrate how to configure base path mapping for API services on AWS:

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

// Create an API Gateway Rest API
const api = new aws.apigateway.RestApi("myApi", {
    description: "This is my API for demonstration purposes",
});

// Deploy the API Gateway
const deployment = new aws.apigateway.Deployment("apiDeployment", {
    restApi: api.id,
    // This empty 'stageName' property is a workaround for a Pulumi issue with missing stages:
    // https://github.com/pulumi/pulumi-aws/issues/340
    stageName: "",
});
const stage = new aws.apigateway.Stage("apiStage", {
    deployment: deployment.id,
    restApi: api.id,
    stageName: "prod",
});

// Create a DNS Record Set for the custom domain. This presumes you have a domain registered.
const domainName = "api.my-custom-domain.com"; // replace with your domain
const customDomain = new aws.apigateway.DomainName("customDomain", {
    domainName: domainName,
    certificateArn: "arn:aws:acm:us-west-2:1234567890:certificate/abc123-123-123-123-abcd123", // replace with your certificate ARN
});

// Setup the base path mapping
const basePathMapping = new aws.apigateway.BasePathMapping("apiMapping", {
    restApi: api.id,
    stageName: stage.stageName,
    domainName: customDomain.domainName,
    // For this example, requests to the base path will be directed to the API.
    basePath: "", // Can specify a base path here, e.g. "v1" to result in "api.my-custom-domain.com/v1"
});

// Output the base URL at which the API is available
export const baseApiUrl = customDomain.domainName.apply(dName => `https://${dName}`);

```

In the code above:

- We import the required modules for Pulumi and AWS.
- We then create an `aws.apigateway.RestApi` resource named `myApi`, which represents our API Gateway.
- After defining the API, we need to deploy it using `aws.apigateway.Deployment` and `aws.apigateway.Stage`.
- To allow the API to be accessed from a custom domain, we set up a `aws.apigateway.DomainName` with your domain name and an ACM certificate ARN.
- Finally, we map the base path to our API Gateway using `aws.apigateway.BasePathMapping`.
- `baseApiUrl` is exported to easily retrieve your API's new base URL programmatically.

Remember to replace `domainName` and `certificateArn` with your actual domain name and ACM certificate ARN. Also, note that DNS resolution and certificate provisioning are assumed to be handled outside of this Pulumi code.

To use this Pulumi code:
1. Save this code in a file with a `.ts` extension, for example, `main.ts`.
2. Install Pulumi and configure your AWS credentials.
3. Run `pulumi stack init` to create a new stack for your project.
4. Run `pulumi up` to deploy your changes to AWS.