Using multiple segments in Amazon API Gateway base path mapping

Amazon API Gateway recently enhanced base path mapping for custom domains by introducing multi-level base path mapping. Before multi-level base path mapping, paths could not contain a forward slash (/) in a base path. This restriction meant that base paths could only consist of a single word (for example, sales) or a concatenation of several words (for example, sales-reporting).

Base path mapping before multi level option

Multi-level base path mapping enables segmented paths, with each segment able to route to a different endpoint. This pattern allows developers to use RESTful URLs to identify the application paths in easy-to-understand patterns. For example, sales-reporting becomes /sales/reporting and /corp-admin becomes /corp/admin.

Base path mapping with multi level option

This pattern also allows developers to add new endpoints to existing custom domains quickly. For example, I add an endpoint for a second version of the sales reporting API. This new version is global reporting only and is reached at /sales/reporting/v2. This change allows me to create a new application with its API Gateway endpoint developed independently from the /sales/reporting application.

Multi-level base path mapping works with REST (ApiGatewayV1) and HTTP (ApiGatewayV2) APIs. The domain and each API must exist in the same account and Region. The API Gateway service handles base path mapping before a request reaches any API. Individual APIs are still responsible for authorization and throttling.

Demo

In this demonstration, I construct an application that consists of the three sub-applications for reporting, reportingV2, and corp. I route to them using multi-level base path mapping as previously shown. To build multi-level base paths, I use the AWS::ApiGatewayV2::DomainName resource for the custom domain and AWS::ApiGatewayV2::ApiMapping for mapping the custom domain’s base path to the appropriate endpoint.

In this example, I have the primary template and three application templates representing the three separate sub-applications. The primary template contains the resource to create the custom domain. It has an AWS::Route53::RecordSet resource that creates the address (A) record for the domain name in an existing zone in Amazon Route 53. This template also uses the AWS::Serverless::Application to create the sub-applications.

The sub-applications are admin, reportingV1, and reportingV2. Each sub-application contains either an AWS::Serverless::HttpApi or AWS::Serverless::API resource to build an API endpoint. The sub-applications also have one or more AWS Lambda functions for business logic within the sub-applications. Finally, each sub-application uses an ApiGatewayV2 mapping resource to create a base path mapping on the primary template’s custom domain.

Deploying the full application

Note that this application is a proof of concept and does not use authorization on the API Gateway endpoints. To use in production, ensure that you first configure authorization. For information on adding authorization to these endpoints, watch this video for HTTP APIs and this video for REST APIs.

To deploy this application, ensure that you have the AWS SAM CLI installed. You also need a ZoneID for an existing zone in Route 53 and a CertARN for an existing SSL certificate in the AWS Certificate Manager. During this process, an A record is created on the existing zone for the custom domain you choose.

With these in place, follow these steps:

Clone the Sessions with Sam repository:

git clone https://github.com/aws-samples/sessions-with-aws-sam.git

Change to the multi-level-mapping directory:
```
cd multi-level-mapping
```
Run the sam deploy command:
```
sam deploy --guided
```
Enter the appropriate information:

SAM interactive deploy process for full application

Deploying part of the application

It’s also possible to deploy this application in parts, as if from different groups. For this application, I add one more endpoint. I like to have some dad jokes handy for my clients, and I keep this under the corp/jokes route. All dad jokes are supplied by https://icanhazdadjoke.com. To deploy this additional sub-application, follow these steps:

Use AWS SAM to deploy a second application
```
sam deploy -t dadjokes.yaml --guided
```
During the interactive process, enter a new name for the stack and profile

SAM interactive deploy process for additional application

The resulting application looks like this:

Final application architecture

Testing the application

During the deployment of this application, you created four endpoints under the same domain name. To test these endpoints using your custom domain, try the following:

https://<your domain>/sales/reporting/global
https://<your domain>/sales/reporting/v2/global
https://<your domain>/sales/reporting/regional
https://<your domain>/corp/admin
https://<your domain>/corp/jokes/ (note: the trailing slash is required)

Be sure to add the HTTPS protocol!

Cleaning up

You built this application using a primary AWS SAM template and three sub-templates. When deployed, it becomes an AWS CloudFormation stack with three nested stacks. To remove all the resources created in this demonstration, run the following command:

aws cloudformation delete-stack –stack-name mlbpm

If you added the jokes API, run the same command for that stack:

aws cloudformation delete-stack –stack-name mlbpm-jokes

Conclusion

Customers tell us that multi-level base path mapping opens up routing options and simplifies how they build applications. API Gateway multi-level base path mapping increases flexibility when routing to multiple sub-applications.

This post demonstrates using RESTful URLs for readable paths and routing. I cover routing to multiple applications based upon the base path segments. Finally, I cover using AWS SAM to deploy a single application with various sub-applications and subsequently add another application.

For more information on building serverless applications with API Gateway and the full serverless product suite, visit https://serverlessland.com for videos, blogs, and tutorials.

#ServerlessForEveryone

AWS Compute Blog