Menu
Amazon API Gateway
Developer Guide

Configure Mock Integration for a Method in API Gateway

Amazon API Gateway supports mock integrations for API methods. This feature enables API developers to generate API responses from API Gateway directly, without the need for an integration backend. As an API developer, you can use this feature to unblock other dependent teams needing to work with an API before the project development is complete. You can also leverage this feature to provision a landing page of your API, which can provide an overview of and navigation to your API. For an example of such a landing page, see the integration request and response of the GET method on the root resource of the example API discussed in Create an API Gateway API from an Example.

As an API developer, you decide how API Gateway responds to a mock integration request. For this, you configure the method's integration request and integration response to associate a response with a given status code. The tasks involve setting up a mapping template in the integration request to specify a supported status code in the request payload and setting up mapping templates, one for a supported status code, in the integration response to provide associated response payloads. At run time API Gateway retrieves the status code from the request payload and invokes the matching template to return the associated response payload. The integration request payload's content type must be application/json and its format must be of {"statusCode": ddd, ... }, where ddd stands for an HTTP status code. The integration response payload's content type can be any of those matching the response data, including application/json, application/xml, text/html, text/plain and etc.

In this section, you will learn how to use the API Gateway console to enable the mock integration for an API method.

Prerequisites

Enable Mock Integration on a Method

  1. Choose an API resource and create a method. In the Setup pane, choose Mock Integration , and then choose Save.

  2. In the Method Execution pane, choose Integration Request.

  3. By default, mock integrations return a 200 HTTP status code. To customize this default behavior, do the following:

    1. Expand Mapping Templates.

    2. For Content-Type, do one of the following:

      • If the desired content type is already visible (for example, application/json), then choose it.

      • If the desired content type is not already visible, then choose Add mapping template, type the desired content type (for example, application/json), and then choose Create.

    3. In the Template editor, type the content of the template you want API Gateway to use to determine which HTTP status code to use in the integration response. The template must output a JSON payload containing the statusCode property. For more information, see Example Request Templates.

    4. Next to Mapping template, choose Save.

  4. For each query string parameter or header parameter you want to add to the method, do the following:

    1. Choose Method Execution, and then choose Method Request.

    2. Choose the arrow next to URL Query String Parameters or HTTP Request Headers, and then choose Add query string or Add header, respectively.

    3. For Name, type the name of the query string parameter or header parameter, and then choose Create a new query string or Create, respectively.

      Note

      To remove a query string parameter or header parameter, choose Cancel or Remove. To change the name of a query string parameter or header parameter, you must remove it and create a new one in its place.

  5. Choose Method Execution, and then choose Method Response.

  6. Do one of the following:

    • If all of the HTTP Status entries you want to use are already visible (for example, 200), then skip ahead to step 8.

    • If any of the HTTP Status entries you want to use are not already visible, then for each missing HTTP Status entry, choose Add Response, choose the HTTP status code that you want to use, and then choose Create.

  7. Choose Method Execution, and then choose Integration Response.

  8. Do one of the following:

    • If all of the Method response status entries you want to use are already visible (for example, 200), then skip ahead to step 10.

    • If any of the Method response status entries you want to use are not already visible, then for each missing Method response status entry, choose Add integration response, for Method response status choose the HTTP Status entry you created earlier, and then choose Save.

  9. For each Method response status entry you want to use, do the following:

    1. Expand the row that corresponds to the Method response status entry you want to use.

    2. For HTTP status regex, type the matching HTTP Status entry (for example, type 400 for a 400 HTTP Status entry or 500 for a 500 HTTP Status entry). Or specify a range of matching HTTP status codes (for example, 5\d{2} matches all 5XX HTTP status codes).

    3. Expand Mapping Templates.

    4. For Content-Type, do one of the following:

      • If the desired content type is already visible (for example, application/json), then choose it.

      • If the desired content type is not already visible, then choose Add mapping template, type the desired content type (for example, application/json), and then choose Create.

    5. In the Template editor, type the contents of the template that you want API Gateway to use to respond to the caller. For more information, see Example Response Templates.

    6. Next to Mapping template, choose Save.

  10. Do one of the following to test the method:

    • Call the method from the API Gateway console. Follow the instructions in Use the Console to Test a Method.

    • Call the method from a web browser, a web debugging proxy tool or the cURL command-line tool, or from your own API. Follow the instructions in Calling an API.

Example Request Templates

The following example shows a request template that always uses the 200 HTTP status code.

Copy
{ "statusCode": 200 }

The following example shows a request template that uses the 200 HTTP status code if the request specifies the petType parameter of cat; 400 if the request specifies dog; and uses 500 otherwise. This example is based on the one in the Map Request Parameters.

Copy
{ #if( $input.params('petType') == "cat" ) "statusCode": 200 #elseif( $input.params('petType') == "dog" ) "statusCode": 400 #else "statusCode": 500 #end }

Example Response Templates

The following two examples show response templates that respond with the same information every time. These examples are based on the one in the Map Request Parameters.

Copy
## Example 400 response. { "Message": "Error: petType not valid." }
Copy
## Example 500 response. { "Message": "Error: petType not valid or not specified." }

The following example shows a response template that responds with the same information every time, but includes the value the caller specified for the petType parameter. This example is based on the one in the Map Request Parameters.

Copy
## Example 200 response for ?petType=cat (response will contain "type": "cat"). { "id": 1, "name": "Kitty", "type": "$input.params('petType')" }