Split large Amazon API Gateway specs up for easier management

Let’s look at some ways you can create APIs.

Vanilla Cloudformation

You can create API Gateway deployments with vanilla CloudFormation. The resources are AWS::ApiGateway::RestApi and AWS:ApiGateway::HttpApi. This is my least favorite way to create APIs. You have to define every method, permission, integration, and route. It’s extremely verbose and difficult to manage. Generally, I recommend avoiding this method.

Serverless Application Model (SAM)

I recommend using SAM to create these respective deployments: AWS::Serverless::Api and AWS::Serverless::HttpApi. These resources provide a shorthand method to create APIs and SAM handles all of the boilerplate code for you. It’s still deployed via CloudFormation but shortens code by as much as 75%.

You should use an OpenAPI spec to specify the details for your API, such as Routes, Methods, and Authentication and then use the DefinitionUri attribute to point to the spec file.

The most basic example of an API is as follows:

I suggest pointing the DefinitionUri attribute to a local file path with your OpenAPI spec…