Initial API Gateway Construct Library

[eladb]

Introduce an initial construct library for API Gateway. By all means it does not cover the entire surface area of API Gateway, but provides basic support for defining API gateway configurations (resources/methods hierarchy).

Integration support includes LambdaIntegration which accepts a lambda.Function, sets up the appropriate permissions and binds it to an API method.

Includes many "smart defaults" at every level such as:

• Automatically define a Deployment and a Stage for the API, which will be recreated every time the API configuration changes (by generating the logical ID of the AWS::ApiGateway::Deployment resource from a hash of the API configuration, similarly to SAM).
• Automatically configure a role for API Gateway to allow writing CloudWatch logs and alarms.
• Specify defaultIntegration at the API level which will apply to all methods without integration.

Supports defining APIs like this:

const integ = new apigw.LambdaIntegration(toysLambdaHandler);
const api = new apigw.RestApi(this, 'my-awesome-api');

api.root.onMethod('GET', new apigw.HttpIntegration('https://amazon.com/toys'));

const toys = api.root.addResource('toys', { defaultIntegration: integ });
toys.addMethod('ANY');

const toy = toys.addResource('{toy}');
toy.addMethod('GET'); // get a toy
toy.addMethod('DELETE'); // remove a toy

See README for more details.

Framework Changes

• resolve: allow object keys to include tokens, as long as they resolvable to strings.
• assert: invoke stack.validateTree() by default for expect(stack) to simulate synthesis.

Not Supported

See #727
See #723

---

Fixes #602, copy: @hassankhan

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

[eladb]

This is blocked by aws/jsii#175

[hassankhan]

Hi @eladb, had a quick look at the PR and I really like the programmatic way of creating an API 👍

That said, I feel like its a teensy bit verbose as compared to what I proposed in on the issue itself. For example, is there any way to mass-define the API and assign Lambda, or should this be done in user code instead? I personally would prefer it being in the CDK instead of user code, because with API Gateway defining similar options for each API endpoint quickly becomes quite tedious (things such as authorization, CORS options etc.) and mistakes can be made.

I couldn't really tell from the code, but I was wondering if in a scenario where you have multiple API Gateways and enable logging for both, will both APIs use the same Account resource and logging IAM role? Also, might it be possible to add 'Endpoint Types' to the checklist above? (i.e. EDGE/REGIONAL).

[eladb]

@hassankhan

Is there any way to mass-define the API and assign Lambda, or should this be done in user code instead?

You can define a defaultIntegration and then you don't have to define it for each method. At the moment you can only define it at the API level, but I am thinking that perhaps it will be valuable to support this at any level of the resource tree:

const api = new apigw.RestApi(this, 'my-api', { defaultIntegration: lambdaInteg });
const toys = api.addResource('toys');
toys.onMethod('GET'); // will implicitly integrate with `lambdaIteg`

From your comment though I think you are also looking for ways to define other defaults for methods such as authentication, etc. Is that correct?

Do you also think that it would be useful to add support for a declarative way to define the entire API in RestApi props?

I couldn't really tell from the code, but I was wondering if in a scenario where you have multiple API Gateways and enable logging for both, will both APIs use the same Account resource and logging IAM role?

There's actually no association between Account and RestApi. Technically, you will have a role/account per API, but API Gateway will only use the last one created I believe, which I think should be fine because the roles will have similar permissions. It's a bit of a hack. Happy to hear if you have a suggestion on a better approach that will not require deploying a separate stack just for this singleton role.

Also, might it be possible to add 'Endpoint Types' to the checklist above? (i.e. EDGE/REGIONAL).

Endpoint types are supported via the endpointTypes prop. For example:

endpointTypes: [ apigw.EndpointType.Edge, apigw.EndpointType.Regional ]

[hassankhan]

You can define a defaultIntegration and then you don't have to define it for each method. At the moment you can only define it at the API level, but I am thinking that perhaps it will be valuable to support this at any level of the resource tree:

I agree, we should be able to define it at any level. One major reason why this is useful is because you may have several lambda.Functions, for which you'd create correspondent apigw.LambdaIntegration instances. Some people (like me) use a single Lambda for their API, but others prefer to do things differently and it is a completely valid use-case.

From your comment though I think you are also looking for ways to define other defaults for methods such as authentication, etc. Is that correct?

That is correct 😄

Do you also think that it would be useful to add support for a declarative way to define the entire API in RestApi props?

Oh my god, that would be mindblowingly amazing 🤯

Happy to hear if you have a suggestion on a better approach that will not require deploying a separate stack just for this singleton role.

I didn't actually, I was just curious to see how you'd handled it, thanks for the explanation 👍

Endpoint types are supported via the endpointTypes prop. For example:

Ahh awesome, perhaps it could be mentioned on the README?

I was thinking, could we potentially have a apigw.Function construct that handles the integration, method and resource configuration?

[eladb]

@hassankhan in the meantime, I've just added support for specifying default integration and method options at all levels of the resource tree. As for a declarative API for describing the tree, I wonder how this interplays with swagger support. At any rate, I will address at a subsequent commit

[eladb]

@rix0rrr can you take a look at the latest version? I think I we are ready for an initial merge

[RomainMuller]

This also kind of asks for a way to make cdk diff gracefully handle the deployment magic (but that's also not an absolute necessity). I don't think any of my comments are blockers (should be considered for future improvements, though).