aws-cloudformation / aws-cloudformation/cloudformation-coverage-roadmap
Add DefinitionSubstitutions to API Gateway definitions
- 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
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