aws-cloudformation / aws-cloudformation/cloudformation-coverage-roadmap

Add DefinitionSubstitutions to API Gateway definitions

Open
#1,233 1 comment 60 reactions 0 assignees View on GitHub
enhancement
Dominant language
No language data
Stars
1.1k
Forks
62
PR merge metrics
No merged PRs in 30d

Description

### Name of the resource

AWS::ApiGateway::RestApi

### Resource name

_No response_

### Description

**Desired change**
Add `DefinitionSubstitutions` to the following `AWS::ApiGateway` resources:

- `AWS::ApiGatewayV2::Api`
- `AWS::ApiGateway::RestApi`

**Reason for change**
OpenAPI specs have become a standard for describing HTTP APIs. When creating a gateway in this manner you're moving out of "CloudFormation land". However, there may be a need to reference various AWS resources from that spec.

E.g. The Gateway team have provided OpenAPI extensions to describe API integrations. So, I might want to have a method call a specified Lambda function, using a specified IAM role:

```
x-amazon-apigateway-integration:
type: aws
uri: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myLambdaFunctionArn}/invocations
credentials: ${myApiGatewayRoleArn}
```

For a newly deployed (or updated) stack, various things will not have hard-coded values, so having the ability to include CF resources in this description would be a benefit.

**Current workarounds**
The best approaches [1][2] I've found to work around this issue involve uploading the OpenAPI spec to S3, then injecting directly back into the template using AWS::Include. However, in the words of the author of [1], this "feels really hacky".

There's also the option of defining your spec directly into the template body, but not having a separate file for the spec has some downsides in the form of code maintenance and also being able to use the file as documentation (the mechanism API Gateway gives you to generate a spec is a pretty poor replacement for this).

**Two birds with one stone**
My original request (https://github.com/aws-cloudformation/cloudformation-coverage-roadmap/issues/1232) suggested allowing CF variables directly inside the body. However thanks to input from @benbridts I realised that using `DefinitionSubstitutions` would make the request:
- Consistent with [how CF does it in StepFunctions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-definitionsubstitutions)
- Compatible with CDK (which can use generated resource IDs, therefore may not work with static CF references in specs)

CDK Example

```
const myLambdaFunction = ...
const myApiGatewayRole = ...

const api = new apigateway.SpecRestApi(this, 'books-api', {
apiDefinition: apigateway.ApiDefinition.fromAsset('path-to-file.json'),
definitionSubstitutions: {
'myLambdaFunctionArn': myLambdaFunction.functionArn,
'myApiGatewayRoleArn ': myApiGatewayRole.roleArn
}
});
```

[1] https://stackoverflow.com/questions/62179893/aws-cdk-how-to-create-an-api-gateway-backed-by-lambda-from-openapi-spec/62811530#62811530
[2] https://scratchpad.blog/serverless/howto/configure-aws-api-gateway-with-swagger/

### Other Details

_No response_

Contributor guide

Open the contributing guide

Research direction

Begin with the AWS::ApiGateway::RestApi and AWS::ApiGatewayV2::Api resources named in the issue; no repository files, tests, or entry points are identified. Read the linked StepFunctions DefinitionSubstitutions documentation and the OpenAPI examples, then confirm the requested property and substitution behavior for both resources.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws
Domain
api, cloud
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.