Introduction

One of my clients asked me to design and develop a service which would sit in front of a SaaS platform utilised across the organisation. There were systems needed to consume data from the SaaS platform through a custom API that was built in front of it. But the problem was that with all the event-driven workflows across the organisation, often times we were hitting the API’s throttling limit. Real time-ness was important but not critical to be down to the millisecond. In order to avoid hitting the SaaS custom API limits, we built an abstraction layer within AWS using API Gateway and DynamoDB with TTLs. This new service would make interaction with the platform smoother and would also serve as a cache layer, satisfying the business requirements without crashing the SaaS platform.

We used the AWS Serverless Application Model to achieve this using CloudFormation. But with all the options available in the DefinitionBody attribute of the API Gateway resource, one can easily get lost.

How to NOT do it if you’re doing it for the first time

Checking the docs for the serverless API definition here, we can see that OpenApiVersion can either follow Swagger 2.0 or one of the OpenApi 3.0 versions. AWS provide a link in their documentation. The tricky bit will be to come up with a DefinitionBody that will do what you want. You could spend (or invest?) time to familiarise yourself with the standard, but I think an easier way to get it done is to configure a simple version of your API through the AWS API Gateway console and then use the magic Export button to download the definition and paste it straight in your CloudFormation file.

Do this instead

The easiest way to get the parameters you want in the definition body attribute of your SAM template is to configure the integration with Lambda along with all the permissions manually through the console and then export the configuration in a YAML of JSON file. You could then put it straight in the DefinitionBody attribute of your SAM template or you could reference from S3 using the AWS::Include transform like so:

...
DefinitionBody:
  Fn::Transform:
    Name: "AWS::Include"
    Parameters:
      Location: !Ref SwaggerFileLocation
...

where SwaggerFileLocation is a parameter pointing to your S3 file with the API definition containing methods, integrations referencing your Lambdas, query parameters, headers and more.