feat(apigateway): add methodresponse support

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

@@ -213,6 +213,10 @@ to allow users revert the stage to an old deployment manually.
 See [awslabs/aws-cdk#723](https://github.com/awslabs/aws-cdk/issues/723) for a
 list of missing features.
 
+### Roadmap
+
+- [ ] Support defining REST API Models [#1695](https://github.com/awslabs/aws-cdk/issues/1695)
+
 ----
 
 This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.

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

@@ -7,6 +7,8 @@ export * from './stage';
 export * from './integrations';
 export * from './lambda-api';
 export * from './vpc-link';
+export * from './methodresponse';
+export * from './model';
 
 // AWS::ApiGateway CloudFormation Resources:
 export * from './apigateway.generated';

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

@@ -2,6 +2,7 @@ import cdk = require('@aws-cdk/cdk');
 import { CfnMethod, CfnMethodProps } from './apigateway.generated';
 import { ConnectionType, Integration } from './integration';
 import { MockIntegration } from './integrations/mock';
+import { MethodResponse } from './methodresponse';
 import { IRestApiResource } from './resource';
 import { RestApi } from './restapi';
 import { validateHttpMethod } from './util';
@@ -34,12 +35,30 @@ export interface MethodOptions {
  */
  apiKeyRequired?: boolean;
 
+ /**
+ * The responses that can be sent to the client who calls the method.
+ * @default None
+ *
+ * This property is not required, but if these are not supplied for a Lambda
+ * proxy integration, the Lambda function must return a value of the correct format,
+ * for the integration response to be correctly mapped to a response to the client.
+ * @see https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-method-settings-method-response.html
+ */
+ methodResponses?: MethodResponse[]
+
+ /**
+ * The request parameters that API Gateway accepts. Specify request parameters
+ * as key-value pairs (string-to-Boolean mapping), with a source as the key and
+ * a Boolean as the value. The Boolean specifies whether a parameter is required.
+ * A source must match the format method.request.location.name, where the location
+ * is querystring, path, or header, and name is a valid, unique parameter name.
+ * @default None
+ */
+ requestParameters?: { [param: string]: boolean };
+
  // TODO:
  // - RequestValidatorId
  // - RequestModels
- // - RequestParameters
- // - MethodResponses
- requestParameters?: { [param: string]: boolean };
 }
 
 export interface MethodProps {
@@ -93,7 +112,8 @@ export class Method extends cdk.Construct {
  authorizationType: options.authorizationType || defaultMethodOptions.authorizationType || AuthorizationType.None,
  authorizerId: options.authorizerId || defaultMethodOptions.authorizerId,
  requestParameters: options.requestParameters,
- integration: this.renderIntegration(props.integration)
+ integration: this.renderIntegration(props.integration),
+ methodResponses: this.renderMethodResponses(options.methodResponses),
  };
 
  const resource = new CfnMethod(this, 'Resource', methodProps);
@@ -188,6 +208,34 @@ export class Method extends cdk.Construct {
  credentials,
  };
  }
+
+ private renderMethodResponses(methodResponses: MethodResponse[] | undefined): CfnMethod.MethodResponseProperty[] | undefined {
+ if (!methodResponses) {
+ // Fall back to nothing
+ return undefined;
+ }
+
+ return methodResponses.map(mr => {
+ let responseModels: {[contentType: string]: string} | undefined;
+
+ if (mr.responseModels) {
+ responseModels = {};
+ for (const contentType in mr.responseModels) {
+ if (mr.responseModels.hasOwnProperty(contentType)) {
+ responseModels[contentType] = mr.responseModels[contentType].modelId;
+ }
+ }
+ }
+
+ const methodResponseProp = {
+ statusCode: mr.statusCode,
+ responseParameters: mr.responseParameters,
+ responseModels,
+ };
+
+ return methodResponseProp;
+ });
+ }
 }
 
 export enum AuthorizationType {

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

@@ -0,0 +1,28 @@
+import { IModel } from './model';
+
+export interface MethodResponse {
+
+ /**
+ * The method response's status code, which you map to an IntegrationResponse.
+ * Required.
+ */
+ statusCode: string;
+
+ /**
+ * Response parameters that API Gateway sends to the client that called a method.
+ * Specify response parameters as key-value pairs (string-to-Boolean maps), with
+ * a destination as the key and a Boolean as the value. Specify the destination
+ * using the following pattern: method.response.header.name, where the name is a
+ * valid, unique header name. The Boolean specifies whether a parameter is required.
+ * @default None
+ */
+ responseParameters?: { [destination: string]: boolean };
+
+ /**
+ * The resources used for the response's content type. Specify response models as
+ * key-value pairs (string-to-string maps), with a content type as the key and a Model
+ * resource name as the value.
+ * @default None
+ */
+ responseModels?: { [contentType: string]: IModel };
+}

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

@@ -0,0 +1,46 @@
+export interface IModel {
+ readonly modelId: string;
+}
+
+/**
+ * Represents a reference to a REST API's Empty model, which is available
+ * as part of the model collection by default. This can be used for mapping
+ * JSON responses from an integration to what is returned to a client,
+ * where strong typing is not required. In the absence of any defined
+ * model, the Empty model will be used to return the response payload
+ * unmapped.
+ *
+ * Definition
+ * {
+ * "$schema" : "http://json-schema.org/draft-04/schema#",
+ * "title" : "Empty Schema",
+ * "type" : "object"
+ * }
+ *
+ * @see https://docs.amazonaws.cn/en_us/apigateway/latest/developerguide/models-mappings.html#models-mappings-models
+ */
+export class EmptyModel implements IModel {
+ public readonly modelId = 'Empty';
+}
+
+/**
+ * Represents a reference to a REST API's Error model, which is available
+ * as part of the model collection by default. This can be used for mapping
+ * error JSON responses from an integration to a client, where a simple
+ * generic message field is sufficient to map and return an error payload.
+ *
+ * Definition
+ * {
+ * "$schema" : "http://json-schema.org/draft-04/schema#",
+ * "title" : "Error Schema",
+ * "type" : "object",
+ * "properties" : {
+ * "message" : { "type" : "string" }
+ * }
+ * }
+ */
+export class ErrorModel implements IModel {
+ public readonly modelId = 'Error';
+}
+
+// TODO: Implement Model, enabling management of custom models.

packages/@aws-cdk/aws-apigateway/test/test.method.ts

@@ -5,7 +5,7 @@ import iam = require('@aws-cdk/aws-iam');
 import cdk = require('@aws-cdk/cdk');
 import { Test } from 'nodeunit';
 import apigateway = require('../lib');
-import { ConnectionType } from '../lib';
+import { ConnectionType, EmptyModel, ErrorModel } from '../lib';
 
 export = {
  'default setup'(test: Test) {
@@ -304,6 +304,63 @@ export = {
  test.done();
  },
 
+ 'methodResponse set one or more method responses via options'(test: Test) {
+ // GIVEN
+ const stack = new cdk.Stack();
+ const api = new apigateway.RestApi(stack, 'test-api', { deploy: false });
+
+ // WHEN
+ new apigateway.Method(stack, 'method-man', {
+ httpMethod: 'GET',
+ resource: api.root,
+ options: {
+ methodResponses: [{
+ statusCode: '200'
+ }, {
+ statusCode: "400",
+ responseParameters: {
+ 'method.response.header.killerbees': false
+ }
+ }, {
+ statusCode: "500",
+ responseParameters: {
+ 'method.response.header.errthing': true
+ },
+ responseModels: {
+ 'application/json': new EmptyModel(),
+ 'text/plain': new ErrorModel()
+ }
+ }
+ ]
+ }
+ });
+
+ // THEN
+ expect(stack).to(haveResource('AWS::ApiGateway::Method', {
+ HttpMethod: 'GET',
+ MethodResponses: [{
+ StatusCode: "200"
+ }, {
+ StatusCode: "400",
+ ResponseParameters: {
+ 'method.response.header.killerbees': false
+ }
+ }, {
+ StatusCode: "500",
+ ResponseParameters: {
+ 'method.response.header.errthing': true
+ },
+ ResponseModels: {
+ 'application/json': 'Empty',
+ 'text/plain': 'Error'
+ }
+ }
+ ]
+ }));
+
+ test.done();
+ },
+
  'multiple integration responses can be used'(test: Test) { // @see https://github.com/awslabs/aws-cdk/issues/1608
  // GIVEN
  const stack = new cdk.Stack();