feat(aws-apigateway): add support for UsagePlan, ApiKey, UsagePlanKey

install.sh

@@ -16,5 +16,6 @@ npm ci --global-style
 export PATH=node_modules/.bin:$PATH
 
 echo "============================================================================================="
-echo "bootstrapping..."
+echo "cleanup and start bootstrapping..."
+lerna clean --yes
 lerna bootstrap --reject-cycles --ci

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

@@ -104,6 +104,57 @@ book.addMethod('GET', getBookIntegration, {
 });
 ```
 
+The following example shows how to use an API Key with a usage plan:
+
+```ts
+const hello = new lambda.Function(this, 'hello', {
+  runtime: lambda.Runtime.NodeJS810,
+  handler: 'hello.handler',
+  code: lambda.Code.asset('lambda')
+});
+
+const api = new apigateway.RestApi(this, 'hello-api', { });
+const integration = new apigateway.LambdaIntegration(hello);
+
+const v1 = api.root.addResource('v1');
+const echo = v1.addResource('echo');
+const echoMethod: apigateway.Method = echo.addMethod('GET', integration, { apiKeyRequired: true });
+
+const usagePlan = new apigateway.UsagePlan(this, 'UsagePlan', {
+  name: 'Basic',
+  description: 'Free tier monthly usage plan',
+  quota: {
+    limit: 10000,
+    period: apigateway.Period.Month
+  },
+  throttle: {
+    rateLimit: 50,
+    burstLimit: 5
+  },
+  apiStages: [
+    {
+      api: api,
+      stage: api.deploymentStage,
+      throttle: [
+        {
+          method: echoMethod,
+          throttle: {
+            rateLimit: 10,
+            burstLimit: 2
+          }
+        }
+      ]
+    }
+  ]
+});
+
+const key = new apigateway.ApiKey(this, 'ApiKey', {
+  resources: [api]
+});
+
+usagePlan.addApiKey(key);
+```
+
 #### Default Integration and Method Options
 
 The `defaultIntegration` and `defaultMethodOptions` properties can be used to

packages/@aws-cdk/aws-apigateway/lib/api-key.ts

@@ -0,0 +1,85 @@
+import { Construct, Resource } from '@aws-cdk/cdk';
+import { CfnApiKey } from './apigateway.generated';
+import { ResourceOptions } from "./resource";
+import { RestApi } from './restapi';
+
+export interface ApiKeyProps extends ResourceOptions {
+  /**
+   * A list of resources this api key is associated with.
+   * @default none
+   */
+  readonly resources?: RestApi[];
+
+  /**
+   * An AWS Marketplace customer identifier to use when integrating with the AWS SaaS Marketplace.
+   * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html#cfn-apigateway-apikey-customerid
+   * @default none
+   */
+  readonly customerId?: string;
+
+  /**
+   * A description of the purpose of the API key.
+   * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html#cfn-apigateway-apikey-description
+   * @default none
+   */
+  readonly description?: string;
+
+  /**
+   * Indicates whether the API key can be used by clients.
+   * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html#cfn-apigateway-apikey-enabled
+   * @default true
+   */
+  readonly enabled?: boolean;
+
+  /**
+   * Specifies whether the key identifier is distinct from the created API key value.
+   * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html#cfn-apigateway-apikey-generatedistinctid
+   * @default false
+   */
+  readonly generateDistinctId?: boolean;
+
+  /**
+   * A name for the API key. If you don't specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the API key name.
+   * @link http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html#cfn-apigateway-apikey-name
+   * @default automically generated name
+   */
+  readonly name?: string;
+}
+
+/**
+ * An API Gateway ApiKey.
+ *
+ * An ApiKey can be distributed to API clients that are executing requests
+ * for Method resources that require an Api Key.
+ */
+export class ApiKey extends Resource {
+  public readonly keyId: string;
+
+  constructor(scope: Construct, id: string, props: ApiKeyProps = { }) {
+    super(scope, id);
+
+    const resource = new CfnApiKey(this, 'Resource', {
+      customerId: props.customerId,
+      description: props.description,
+      enabled: props.enabled || true,
+      generateDistinctId: props.generateDistinctId,
+      name: props.name,
+      stageKeys: this.renderStageKeys(props.resources)
+    });
+
+    this.keyId = resource.ref;
+  }
+
+  private renderStageKeys(resources: RestApi[] | undefined): CfnApiKey.StageKeyProperty[] | undefined {
+    if (!resources) {
+      return undefined;
+    }
+
+    return resources.map((resource: RestApi) => {
+      const restApi = resource;
+      const restApiId = restApi.restApiId;
+      const stageName = restApi.deploymentStage!.stageName.toString();
+      return { restApiId, stageName };
+    });
+  }
+}

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

@@ -6,6 +6,8 @@ export * from './deployment';
 export * from './stage';
 export * from './integrations';
 export * from './lambda-api';
+export * from './api-key';
+export * from './usage-plan';
 export * from './vpc-link';
 export * from './methodresponse';
 export * from './model';

packages/@aws-cdk/aws-apigateway/lib/usage-plan.ts

@@ -0,0 +1,211 @@
+import { Token } from '@aws-cdk/cdk';
+import { Construct, Resource } from '@aws-cdk/cdk';
+import { ApiKey } from './api-key';
+import { CfnUsagePlan, CfnUsagePlanKey } from './apigateway.generated';
+import { Method } from './method';
+import { RestApi } from './restapi';
+import { Stage } from './stage';
+import { validateInteger } from './util'
+
+/**
+ * Container for defining throttling parameters to API stages or methods.
+ * @link https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-request-throttling.html
+ */
+export interface ThrottleSettings {
+  /**
+   * The API request steady-state rate limit (average requests per second over an extended period of time)
+   * 
+   * Type: Integer
+   */
+  readonly rateLimit?: number;
+
+  /**
+   * The maximum API request rate limit over a time ranging from one to a few seconds.
+   * 
+   * Type: Integer
+   */
+  readonly burstLimit?: number;
+}
+
+/**
+ * Time period for which quota settings apply.
+ */
+export enum Period {
+  Day = 'DAY',
+  Week = 'WEEK',
+  Month = 'MONTH'
+}
+
+/**
+ * Specifies the maximum number of requests that clients can make to API Gateway APIs.
+ */
+export interface QuotaSettings {
+  /**
+   * The maximum number of requests that users can make within the specified time period.
+   * 
+   * Type: Integer
+   */
+  readonly limit?: number;
+
+  /**
+   * For the initial time period, the number of requests to subtract from the specified limit.
+   * 
+   * Type: Integer
+   */
+  readonly offset?: number;
+
+  /**
+   * The time period for which the maximum limit of requests applies.
+   */
+  readonly period?: Period;
+}
+
+/**
+ * Represents per-method throttling for a resource.
+ */
+export interface ThrottlingPerMethod {
+  readonly method: Method,
+  readonly throttle: ThrottleSettings
+}
+
+/**
+ * Type of Usage Plan Key. Currently the only supported type is 'API_KEY'
+ */
+export enum UsagePlanKeyType {
+  ApiKey = 'API_KEY'
+}
+
+/**
+ * Represents the API stages that a usage plan applies to.
+ */
+export interface UsagePlanPerApiStage {
+  readonly api?: RestApi,
+  readonly stage?: Stage,
+  readonly throttle?: ThrottlingPerMethod[]
+}
+
+export interface UsagePlanProps {
+  /**
+   * API Stages to be associated which the usage plan.
+   */
+  readonly apiStages?: UsagePlanPerApiStage[],
+
+  /**
+   * Represents usage plan purpose.
+   */
+  readonly description?: string,
+
+    /**
+   * Number of requests clients can make in a given time period.
+   */
+  readonly quota?: QuotaSettings
+
+  /**
+   * Overall throttle settings for the API.
+   */
+  readonly throttle?: ThrottleSettings,
+
+  /**
+   * Name for this usage plan.
+   */
+  readonly name?: string,
+}
+
+export class UsagePlan extends Resource {
+  public readonly usagePlanId: string;
+
+  constructor(scope: Construct, name: string, props: UsagePlanProps = { }) {
+    super(scope, name);
+    let resource: CfnUsagePlan;
+
+    if (props !== undefined) {
+      resource = new CfnUsagePlan(this, 'Resource', {
+        apiStages: this.renderApiStages(props),
+        description: props.description,
+        quota: this.renderQuota(props),
+        throttle: this.renderThrottle(props.throttle),
+        usagePlanName: props.name,
+      });
+    } else {
+      resource = new CfnUsagePlan(this, 'Resource');
+    }
+
+    this.usagePlanId = resource.ref;
+  }
+
+  public addApiKey(apiKey: ApiKey): void {
+    new CfnUsagePlanKey(this, 'UsagePlanKeyResource', {
+      keyId: apiKey.keyId,
+      keyType: UsagePlanKeyType.ApiKey,
+      usagePlanId: this.usagePlanId
+    });
+  }
+
+  private renderApiStages(props: UsagePlanProps): CfnUsagePlan.ApiStageProperty[] | undefined {
+    if (props.apiStages && props.apiStages.length > 0) {
+
+      const apiStages: CfnUsagePlan.ApiStageProperty[] = [];
+      props.apiStages.forEach((apiStage: UsagePlanPerApiStage) => {
+
+        const apiId = apiStage.api ? apiStage.api.restApiId : undefined;
+        const stage = apiStage.stage ? apiStage.stage.stageName.toString() : undefined;
+        const throttle = this.renderThrottlePerMethod(apiStage.throttle);
+        apiStages.push({
+          apiId,
+          stage,
+          throttle
+        });
+      });
+      return apiStages;
+    }
+
+    return undefined;
+  }
+
+  private renderQuota(props: UsagePlanProps): CfnUsagePlan.QuotaSettingsProperty | undefined {
+    if (props.quota === undefined) {
+      return undefined;
+    } else {
+      const limit = props.quota ? props.quota.limit : undefined; 
+      validateInteger(limit, 'Throttle quota limit')
+      return {
+        limit: limit,
+        offset: props.quota ? props.quota.offset : undefined,
+        period: props.quota ? props.quota.period : undefined
+      };  
+    }
+  }
+
+  private renderThrottle(props: ThrottleSettings | undefined): CfnUsagePlan.ThrottleSettingsProperty | Token {
+    let ret: (CfnUsagePlan.ThrottleSettingsProperty | Token) = { };
+    if (props !== undefined) {
+      const burstLimit = props.burstLimit
+      validateInteger(burstLimit, 'Throttle burst limit')
+      const rateLimit = props.rateLimit
+      validateInteger(rateLimit, 'Throttle rate limit')
+
+      ret = {
+        burstLimit: burstLimit,
+        rateLimit: rateLimit
+      }
+    }
+    return ret;
+  }
+
+  private renderThrottlePerMethod(throttlePerMethod?: ThrottlingPerMethod[]): {
+    [key: string]: (CfnUsagePlan.ThrottleSettingsProperty | Token)
+  } {
+    let ret: { [key: string]: (CfnUsagePlan.ThrottleSettingsProperty | Token) } = {};
+
+    if (throttlePerMethod && throttlePerMethod.length > 0) {
+      throttlePerMethod.forEach((value: ThrottlingPerMethod) => {
+        const method: Method = value.method;
+        // this methodId is resource path and method for example /GET or /pets/GET
+        const methodId = `${method.resource.path}/${method.httpMethod}`;
+        ret[methodId] = this.renderThrottle(value.throttle);
+      });
+    }
+
+    return ret;
+  }
+}

packages/@aws-cdk/aws-apigateway/lib/util.ts

@@ -67,3 +67,9 @@ export function parseAwsApiCall(path?: string, action?: string, actionParams?: {
 
   throw new Error(`Either "path" or "action" are required`);
 }
+
+export function validateInteger(property: number | undefined, messagePrefix: string) {
+  if (property && !Number.isInteger(property)) {
+    throw new Error(`${messagePrefix} should be an integer`);
+  }
+}