Add HTTP API component

[danielrbradley]

API Gateway V2 allows construction using plain resources rather than requiring swagger specs to be generated. This makes it possible to create a component which transparently exposes all features of the underlying resources while improving usability.

This component focuses specifically on setting up a HTTP API rather than WebSocket API. The WebSocket API should be a separate component in a similar pattern to the Fargate vs EC2 ECS components.

Encapsulates:

1. The root API resource
2. A map of routes which can reference integrations and authorizers. The key is the route e.g. GET /pets
3. Optional map of integrations
4. Optional map of authorizers
5. Optional map of stages (defaults to a single default stage which will autodeploy)
6. Optional map of domain mappings. The key is the domain name to either create or link to.

Fixes pulumi/pulumi-aws-apigateway#6

Examples

Simplest lambda setup - route-specific integration, default stage and deployment auto-created. Lambda permission for API Gateway also auto-created.

const api = new awsx.apigatewayv2.HttpApi("api", {
  routes: {
    "GET /path": {
      integration: {
        lambdaArn: apiLambda.arn,
      },
    },
  },
};

Re-usable integrations:

export const api = new awsx.apigatewayv2.HttpApi("api", {
  routes: {
    "GET /": {
      integrationName: "my-lambda",
    },
  },
  integrations: {
    "my-lambda": {
      lambdaArn: apiLambda.arn,
    },
  },
});

Custom stages & domains:

const api = new awsx.apigatewayv2.HttpApi("api", {
  routes: {
    "GET /{proxy+}'": {
      integration: {
        lambdaArn: apiLambda.arn,
      },
    },
  },
  stages: {
    test: {},
    prod: {
      accessLogSettings: {
        destinationArn: logGroup.arn,
        format: `{ "requestId":"$context.requestId", "ip": "$context.identity.sourceIp", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod","routeKey":"$context.routeKey", "status":"$context.status","protocol":"$context.protocol", "responseLength":"$context.responseLength", "extendedRequestId": "$context.extendedRequestId" }`,
      }
    },
  },
  domainMappings: {
    "example.com": {
      stage: "prod",
      domainId: domain.id,
    },
  },
});

[lukehoban]

A few questions before reviewing details here:

1. How do we decide whether this lives in awsx or aws-apigateway? I can see arguments for both, but generally feels like we need articulated principles for these and future new components
2. I believe Add support for HTTP API pulumi-aws-apigateway#6 is the issue tracking this work? (Where we could discuss the approach to addressing).
3. What would be our content goal once this is landed? Would we update the serverless arch templates to use this? Would we update the AWS guides to use this? Will we update examples to use this?

[danielrbradley]

Thanks for the initial questions @lukehoban

1. How do we decide whether this lives in awsx or aws-apigateway? I can see arguments for both, but generally feels like we need articulated principles for these and future new components

I believe this should sit within the main AWSx library for a couple of reasons:

1. Discoverability. A number of our AWS templates automatically import AWSx already. This makes it easy for a user to see available components by browsing the SDK rather than having to search for other packages. Similarly, it's easier browsing the available resources within a single package within the registry comparared to trawling through the haphazardly named list of all packages of varying quality (e.g. see "quickstart" in the registry).
2. Implementation. We already have sophisticated tooling within AWSx which makes it easy to implement this derrived from the underlying resource options. Extracting these tools out to make them available to the aws-apigateway library would require significantly time which would need planning in advance.

2. I believe Add support for HTTP API pulumi-aws-apigateway#6 is the issue tracking this work

👍 added a reference in the description. I think it's easier to iterate on a concrete design as previous discussions and documents around these designs and the split have failed to gain traction. This is my attempt at moving the issue forwards by making a working proposal.

3. What would be our content goal once this is landed?

1. Update the templates, example & guides relating to API Gateways
2. Add a notice to the aws-apigateway package that we recommend using this component within AWSx instead.

Alternatively, we could look at also moving some of the guides content to be within the registry docs similar to the new VPC registry docs - where we're able to embed more of a guide right into the VPC resource page.

[pierskarsenbarg]

Couple of things:

1. Can we avoid AWS leakage by not having the v2 in the module name? This is an abstraction so doesn't need to match the underlying provider (plus people will ask if the aws-api-gateway package is going to be decommissioned and what should they use for rest api instead). We could therefore have awsx.apigateway.HttpApi and awsx.apigateway.RestApi which feels a lot better
2. Can we either lift and shift or rewrite the aws-apigateway into AWSx and actually archive the old one? If what you're suggesting means that this becomes more discoverable then that's good, right?