feat(apigateway): create RestApi from an OpenAPI spec

[bdgmb2]

Commit Message

feat(apigateway): create RestApi from an OpenAPI spec

Co-authored-by: Niranjan Jayakar nija@amazon.com

Ability to import an OpenAPI definition to an API Gateway Rest API.
The definition can either be a file as a local asset, inline JSON or a
key in an S3 bucket.

closes #4421

End Commit Message

---

Changes in this PR were modeled after the aws-lambda package, specifically how that package deals with handling lambda function code. This PR introduces no breaking changes: adding an API definition is optional, and developers can continue to add resources and methods to an API even after an API definition is specified if they choose.

This does not close issue #1461 - that issue is asking for a much bigger feature. This PR does not generate constructs from a swagger/openapi spec - it relies on API Gateway's ability to do this during CloudFormation deployment.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject6AEA49D1-qxepHUsryhcu
• Commit ID: 0dcd6c5
• Result: FAILED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject6AEA49D1-qxepHUsryhcu
• Commit ID: 343abb8
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject6AEA49D1-qxepHUsryhcu
• Commit ID: f021bfc
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject6AEA49D1-qxepHUsryhcu
• Commit ID: cfd5620
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[nija-at]

Thanks for submitting this PR.

Before I get into the code, I believe some of the properties in RestApiProps may conflict or not be compatible when an openapi definition is provided, such as, binaryMediaTypes and cloneFrom. What happens when they are specified along with the openapi definition?

Would it be cleaner if there's a different entry point when starting off with a OpenAPI definition?

[bdgmb2]

Taking a look at the CloudFormation Docs for the Rest API, there appears to be no info on what happens when these additional props are given. Not wanting to assume everything's OK, I tried a bunch of different configurations in the integration tests - passing in different combinations of RestApiProps, and all appear to synthesize and deploy without errors (the docs seem to be right, go figure).

Some more information on cloneFrom: If you specify a specification and cloneFrom in the same resource, API Gateway first clones the Rest API, then applies the specification, overwriting if necessary. It turns out this behavior is also documented in the Rest API docs.

Because users can specify any of the other Rest API props, I don't think moving this to a static constructor/different entry point for an API definition (i.e. RestApi.fromDefinition()) would be useful - these other props are only writable in the constructor and I can see the use case where a user would want to specify these additional props alongside their API definition. That doesn't mean I can't add the other entry point, though - if you'd still like the other entry point (or something else entirely), let me know and I'll change the PR.

[nija-at]

I tried a bunch of different configurations in the integration tests - passing in different combinations of RestApiProps, and all appear to synthesize and deploy without errors (the docs seem to be right, go figure).

Thanks for trying these out!

While there were no errors, what was the final behaviour?
If the same property is specified in both RestApiProps and the OpenAPI definition (say binaryMediaTypes in RestApiProps and the x-amazon-apigateway-binary-media-types in OpenAPI), which one takes precedent?

There are two ways to go about this - either document this behaviour or create a different entry point (either a RestApi.fromDefinition() or a subclass of RestApi). The new entry point, in addition to the OpenAPI definition, will not allow only properties that can be specified in the OpenAPI definition.

I can see the use case where a user would want to specify these additional props alongside their API definition

Can you expand? Wouldn't this be more confusing, especially when there are two different values across these two definitions?

Further, were you able to check if calling addMethod() and/or addResource() on a RestApi that starts off with an OpenAPI definition correctly adds a new Method or a new Resource?
What happens when the Method or Resource has the same path and/or httpMethod as is present in the OpenAPI definition? Does this overwrite and if so, which way does the overwrite work?

You'll need to expand on the README and add details on this behaviour.

[bdgmb2]

Thanks for the questions, I'll see if I can clarify:

The OpenAPI specification always takes precedent over CloudFormation constructs. For example, if I create a GET method on a /test resource in the specification, then call addResource('test').addMethod('GET'), CloudFormation will still accept the CDK-synthesized resource and method but they will be ignored for the one in the OpenAPI spec. This actually is documented in the API Gateway Documentation, but it's in the wrong section - this section covers updating an existing API from the CLI (which isn't relevant to this PR) but the behavior is the same.

I can confirm calling addResource and addMethod will create those Rest API constructs alongside the spec but only as long as this new item doesn't conflict with the API specification (otherwise the specification takes precedent).

I agree that just "telling" the user this precedence in the README isn't enough - this could lead to "shooting yourself in the foot", which I imagine is not what CDK wants to allow the user to do. I will resubmit the PR with the README edited and a clear separation in code between creating a Rest API with an OpenAPI specification and the current method (addResource, addMethod, etc.)

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject6AEA49D1-qxepHUsryhcu
• Commit ID: 1ada84b
• Result: FAILED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject6AEA49D1-qxepHUsryhcu
• Commit ID: 63c5550
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[bdgmb2]

Updated the PR with the separation. This was a bigger change than I thought - adding an OpenAPI specification makes some props irrelevant, but not all (like the binaryMediaTypes you mentioned but not the CloudWatch roles/policies and domain names). A static fromAPIDefinition wouldn't make sense, as the user may still need to specify these other props during construction. To ensure we keep backwards compatibility, I've made a new APIDefinitionRestApi virtual construct. The regular RestApi construct and this new construct both inherit an abstract class that represents the union of common props both types should share.

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject6AEA49D1-qxepHUsryhcu
• Commit ID: 3b36e02
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[ayush987goyal]

Thanks a lot @bdgmb2 for this!

[nija-at]

This is looking much better. Thanks for making these changes.

I've have not gone through through this completely, but publishing my comments so far.

[bdgmb2]

Hello everyone, my apologies as it may appear this PR hasn't gotten any attention from me over the past couple days.
My team was originally blocked by this functionality, but we have instead used the L2->L1 escape hatch and are passing our OpenAPI spec to the Cfn construct. This PR is no longer on our team's radar so it's dropped off my (professional) work tasks, but I will do my best to make the requested changes in my spare time.
@nija-at It looks like you're going to make some decisions based on #7097 in the next couple days. I'll wait for further instructions so I don't need to make multiple changes to push this through.

[nija-at]

@bdgmb2 - Thanks for letting us know that this is going to be on your spare time. We really appreciate the effort! 😊

The PR #7097 has no decisions that will impact this PR, so you can proceed with the changes suggested. I had only referenced to your PR - this one - as how the OpenAPI support should be modeled.

I would appreciate it if you could comment on here, at any point, if you're unable to take this PR forward.

Pull request has been modified.

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject6AEA49D1-qxepHUsryhcu
• Commit ID: 68f693d
• Result: FAILED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject6AEA49D1-qxepHUsryhcu
• Commit ID: e936e99
• Result: FAILED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject6AEA49D1-qxepHUsryhcu
• Commit ID: be034ac
• Result: FAILED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject6AEA49D1-qxepHUsryhcu
• Commit ID: 7f06ccc
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject6AEA49D1-qxepHUsryhcu
• Commit ID: 8563060
• Result: FAILED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

more scrutiny

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject6AEA49D1-qxepHUsryhcu
• Commit ID: 7d85a9a
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject6AEA49D1-qxepHUsryhcu
• Commit ID: f85618c
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[mergify]

Thank you for contributing! Your pull request will be updated from master and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).