feat(apigatewayv2): http api

packages/@aws-cdk/aws-apigatewayv2/README.md

@@ -19,6 +19,100 @@
 
 This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
 
+
+## Introduction
+
+Amazon API Gateway is an AWS service for creating, publishing, maintaining, monitoring, and securing REST, HTTP, and WebSocket APIs at any scale. API developers can create APIs that access AWS or other web services, as well as data stored in the AWS Cloud. As an API Gateway API developer, you can create APIs for use in your own client applications. Or you can make your APIs available to third-party app developers. For more infomation, read the [Amazon API Gateway Developer Guide](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html).
+
+
+## API
+
+This construct library at this moment implements API resources from [AWS::ApiGatewayV2::Api](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html), which supports both `WebSocket APIs` and `HTTP APIs`.
+
+For more information about WebSocket APIs, see [About WebSocket APIs in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-overview.html) in the _API Gateway Developer Guide_. For more information about HTTP APIs, see [HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html) in the _API Gateway Developer Guide_.
+
+To create [REST APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html), use `@aws-cdk/aws-apigateway` instead.
+
+
+### HTTP API
+
+`CfnApi` is the L1 construct to create either `WebSocket APIs` or `HTTP APIs`. At this moment, `HTTP APIs` supports both `Lambda Proxy Integration` and `HTTP Proxy Integration`. See [Working with AWS Lambda Proxy Integrations for HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html) and [Working with HTTP Proxy Integrations for HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-http.html) for more information.
+
+
+To create `HTTP APIs` with `Lambda Proxy Integration`, simply use  `LambdaProxyApi`.
+
+
+```ts
+// Create a HTTP API with Lambda Proxy Integration as its $default route
+const api = new apigatewayv2.LambdaProxyApi(stack, 'LambdaProxyApi', {
+  handler
+});
+```
+
+To create `HTTP APIs` with `HTTP Proxy Integration`, use `HttpProxyApi` instead.
+
+```ts
+// Create a HTTP API with HTTP Proxy Integration
+new apigatewayv2.HttpProxyApi(stack, 'HttpProxyApi', {
+  url: 'https://aws.amazon.com'
+});
+```
+
+
+### WebSocket API
+
+The WebSocket API is not implemented yet in this L2 construct library, however, as `Api` class is provided, it's still possible to create the Websocket APIs with the `Api` class.
+
+
+## Route
+
+`Routes` direct incoming API requests to backend resources. `Routes` consist of two parts: an HTTP method and a resource path—for example, `GET /pets`. You can define specific HTTP methods for your route, or use the `ANY` method to match all methods that you haven't defined for a resource. You can create a `$default route` that acts as a catch-all for requests that don’t match any other routes. See [Working with Routes for HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html).
+
+When you create HTTP APIs with either `Lambda Proxy Integration` or `HTTP Proxy Integration`, the `$default route` will be created as well.
+
+To create a specific route for an existing `Api` resource, specify the `httpPath` and an optional `httpMethod` property.
+
 ```ts
-import apigatewayv2 = require('@aws-cdk/aws-apigatewayv2');
+// create a specific 'GET /some/very/deep/route/path' route with Lambda proxy integration for an existing HTTP API
+const someDeepLambdaRoute = new apigatewayv2.LambdaRoute(stack, 'SomeLambdaRoute', {
+  api,
+  handler,
+  httpPath: '/some/very/deep/route/path',
+  // optional
+  httpMethod: HttpMethod.GET 
+});
 ```
+
+### `addLambdaRoute` and `addHttpRoute`
+
+To extend the routes from an existing HTTP API, use `addLambdaRoute` for Lambda proxy integration or `addHttpRoute` for HTTP Proxy Intgegration.
+
+Consider the providewd example above
+
+```ts
+// create a specific 'GET /some/very/deep/route/path' route with Lambda proxy integration for an existing HTTP API
+const someDeepLambdaRoute = new apigatewayv2.LambdaRoute(stack, 'SomeLambdaRoute', {
+  api,
+  handler,
+  httpPath: '/some/very/deep/route/path',
+  httpMethod: HttpMethod.GET
+});
+
+someDeepLambdaRoute
+  // HTTP ANY /some/very/deep/route/path/bar
+  .addLambdaRoute('bar', 'SomeDeepPathBar', {
+    target: handler,
+    method: apigatewayv2.HttpMethod.GET
+  })
+  // HTTP ANY /some/very/deep/route/path/bar/checkip
+  .addHttpRoute('checkip', 'SomeDeepPathBarCheckIp', {
+    targetUrl: 'https://checkip.amazonaws.com',
+    method: apigatewayv2.HttpMethod.ANY
+  });
+
+// print the full URL in the Outputs
+new cdk.CfnOutput(stack, 'SomeDeepLambdaRouteURL', {
+  value: someDeepLambdaRoute.fullUrl
+});
+```
+

packages/@aws-cdk/aws-apigatewayv2/lib/api.ts

@@ -0,0 +1,239 @@
+import * as lambda from '@aws-cdk/aws-lambda';
+import * as cdk from '@aws-cdk/core';
+import * as apigatewayv2 from '../lib';
+import { CfnApiProps } from './apigatewayv2.generated';
+
+/**
+ * the HTTP API interface
+ */
+export interface IApi extends cdk.IResource {
+  /**
+   * The ID of this API Gateway HTTP Api.
+   * @attribute
+   */
+  readonly apiId: string;
+}
+/**
+ * the ApiBase interface
+ */
+export interface IApiBase extends IApi {
+  /**
+   * http url of this api
+   */
+  readonly url: string
+}
+
+/**
+ * HttpProxyApi interface
+ */
+export interface IHttpProxyApi extends IApi {}
+/**
+ * LambdaProxyApi interface
+ */
+export interface ILambdaProxyApi extends IApi { }
+
+abstract class ApiBase extends cdk.Resource implements IApi {
+  /**
+   * API ID
+   */
+  public abstract readonly apiId: string;
+  /**
+   * API URL
+   */
+  public abstract readonly url: string;
+}
+
+/**
+ * API properties
+ */
+export interface ApiProps extends cdk.StackProps {
+  /**
+   * API Name
+   * @default - the logic ID of the API
+   */
+  readonly apiName?: string;
+  /**
+   * API protocol
+   * @default HTTP
+   */
+  readonly protocol?: ApiProtocol;
+  /**
+   * the default integration target of this API
+   */
+  readonly target: string;
+
+}
+
+/**
+ * API protocols
+ */
+export enum ApiProtocol {
+  /**
+   * HTTP protocol
+   */
+  HTTP = 'HTTP',
+  /**
+   * Websocket protocol
+   */
+  WEBSOCKET = 'WEBSOCKET'
+}
+
+/**
+ * Api Resource Class
+ */
+export class Api extends ApiBase implements IApi {
+  /**
+   * import from ApiId
+   */
+  public static fromApiId(scope: cdk.Construct, id: string, apiId: string): IApi {
+    class Import extends cdk.Resource implements IApi {
+      public readonly apiId = apiId;
+    }
+
+    return new Import(scope, id);
+  }
+  /**
+   * the API identifer
+   */
+  public readonly apiId: string;
+  /**
+   * AWS partition either `aws` or `aws-cn`
+   */
+  public readonly partition: string;
+  /**
+   * AWS region of this stack
+   */
+  public readonly region: string;
+  /**
+   * AWS account of this stack
+   */
+  public readonly account: string;
+  /**
+   * AWS domain name either `amazonaws.com` or `amazonaws.com.cn`
+   */
+  public readonly awsdn: string;
+  /**
+   * the full URL of this API
+   */
+  public readonly url: string;
+
+  constructor(scope: cdk.Construct, id: string, props?: ApiProps) {
+    super(scope, id, {
+      physicalName: props?.apiName || id,
+    });
+
+    this.region = cdk.Stack.of(this).region;
+    this.partition = this.region.startsWith('cn-') ? 'aws-cn' : 'aws';
+    this.account = cdk.Stack.of(this).account;
+    this.awsdn = this.partition === 'aws-cn' ? 'amazonaws.com.cn' : 'amazonaws.com';
+
+    const apiProps: CfnApiProps = {
+      name: this.physicalName,
+      protocolType: props?.protocol ?? ApiProtocol.HTTP,
+      target: props?.target
+    };
+    const api = new apigatewayv2.CfnApi(this, 'Resource', apiProps );
+    this.apiId = api.ref;
+    this.url = `https://${this.apiId}.execute-api.${this.region}.${this.awsdn}`;
+  }
+
+}
+
+/**
+ * LambdaProxyApi properties interface
+ */
+export interface LambdaProxyApiProps  {
+  /**
+   * API name
+   * @default - the logic ID of the API
+   */
+  readonly apiName?: string,
+  /**
+   * Lambda handler function
+   */
+  readonly handler: lambda.IFunction
+}
+
+/**
+ * HttpProxyApi properties interface
+ */
+export interface HttpProxyApiProps  {
+  /**
+   * API Name
+   * @default - the logic ID of the API
+   */
+  readonly apiName?: string,
+  /**
+   * API URL
+   */
+  readonly url: string
+}
+
+/**
+ * API with Lambda Proxy integration as the default route
+ */
+export class LambdaProxyApi extends Api implements ILambdaProxyApi {
+  /**
+   * import from api id
+   */
+  public static fromLambdaProxyApiId(scope: cdk.Construct, id: string, lambdaProxyApiId: string): ILambdaProxyApi {
+    class Import extends cdk.Resource implements ILambdaProxyApi {
+      public readonly apiId = lambdaProxyApiId;
+    }
+    return new Import(scope, id);
+  }
+  /**
+   * the root route of the API
+   */
+  public root?: apigatewayv2.IRouteBase;
+  constructor(scope: cdk.Construct, id: string, props: LambdaProxyApiProps) {
+    super(scope, id, {
+      target: props.handler.functionArn
+    });
+
+    new lambda.CfnPermission(this, 'Permission', {
+      action: 'lambda:InvokeFunction',
+      principal: 'apigateway.amazonaws.com',
+      functionName: props.handler.functionName,
+      sourceArn: `arn:${this.partition}:execute-api:${this.region}:${this.account}:${this.apiId}/*/*`,
+    });
+
+    // this.root = new RootRoute(this, 'RootRoute', this, {
+    //   target: props.handler.functionArn,
+    // });
+
+    new cdk.CfnOutput(this, 'LambdaProxyApiUrl', {
+      value: this.url
+    });
+  }
+}
+
+/**
+ * API with HTTP Proxy integration as the default route
+ */
+export class HttpProxyApi extends Api implements IHttpProxyApi  {
+  /**
+   * import from api id
+   */
+  public static fromHttpProxyApiId(scope: cdk.Construct, id: string, httpProxyApiId: string): IHttpProxyApi {
+    class Import extends cdk.Resource implements IHttpProxyApi {
+      public readonly apiId = httpProxyApiId;
+    }
+    return new Import(scope, id);
+  }
+
+  /**
+   * the root route of the API
+   */
+  public root?: apigatewayv2.IRouteBase;
+  constructor(scope: cdk.Construct, id: string, props: HttpProxyApiProps) {
+    super(scope, id, {
+      target: props.url,
+      apiName: props.apiName ?? id
+    });
+
+    new cdk.CfnOutput(this, 'HttpProxyApiUrl', {
+      value: this.url
+    });
+  }
+}

packages/@aws-cdk/aws-apigatewayv2/lib/index.ts

@@ -1,2 +1,4 @@
 // AWS::APIGatewayv2 CloudFormation Resources:
 export * from './apigatewayv2.generated';
+export * from './api';
+export * from './route';