Amazon API Gateway
Developer Guide

Create an API Gateway API from an Example

The Amazon API Gateway console now provides an option for you to create an API Gateway API by example, with helpful hints provided along the way. If you are new to API Gateway, you may find it useful as a learning tool. The following steps walk you through using this create-by-example option to create and test the example API.

  1. Do one of the following:

    1. For the first API in your account, choose Get Started from the API Gateway console welcome page:

      If prompted with a modal dialog box containing hints at a stage of the process, choose OK to close the modal dialog and continue.

    2. For your next API, choose Create API from the API Gateway APIs home page:

  2. Under Create new API, select Examples API and then choose Import to create the example API. For your first API, the API Gateway console will start with this option as default.

    You can scroll down the Swagger definition for details of this example API before choosing Import.

  3. The resulting display shows the newly created API:

    The API Gateway navigation pane on the left shows your available APIs, any API keys, custom domain names and client certificates that you created for your APIs, as well as the settings for logging your APIs' performance metrics. API-specific resources, deployment, custom authorizers and payload-mapping data models are organized under individual APIs.

    The Resources pane in the middle shows the structure of the selected API as a tree of nodes. API methods defined on each resource are edges of the tree. When a resource is selected, all of its methods are listed in the Methods pane on the right. Displayed under each method is a brief summary of the method, including its endpoint URL, authorization type, and API Key requirement.

  4. To view the details of a method, to modify its set-up, or to test the method invocation, choose the method name from either the method list or the resource tree.

    The resulting Method Execution pane for the chosen method presents a logical view of the method's structure and behaviors: a client accesses a back-end service by interacting with the API through Method Request. API Gateway translates the client request, if necessary, into the form acceptable to the back end before forwarding the request to the back end. The transformed request is known as the integration request and is depicted by Integration Request in the display. Similarly, the response from the back end goes through Integration Response and then Method Response before being received by the client. Again, if necessary, API Gateway maps the response from the form shaped in the back end to a form expected by the client.

    For the POST method on this API's root (/) resource, the method's integration request shows that the method is integrated with the endpoint of in the back end. The method request payload will be passed through to the integration request without modification. The GET / method request uses the MOCK integration type and is not tied to any endpoint in the back end. When the method is called, the API Gateway simply accepts the request and immediately returns a response, by way of from Integration Response to Method Response. You can use the mock integration to test an API without requiring a back-end endpoint. You can also use it to serve a local response. In fact, the example API uses it to return a local HTML page as the home page of the API. It uses a mapping template to generate the home page in Integration Response.

    As an API developer, you control the behaviors of your API's front-end interactions by configuring the method request and a method response. You control the behaviors of your API's back-end interactions by setting up the integration request and integration response. They involve data mappings between a method and its corresponding integration. We will cover the method setup in Build an API Gateway API to Expose an HTTP Endpoint. For now, we focus on testing the API to provide an end-to-end user experience.

  5. Choose Test shown on Client (as shown in the previous image) to start testing. Enter the following {"type": "dog","price": 249.99} payload into the Request Body before choosing the Test button.

    The input specifies the attributes of the pet that we wish to add to the list of pets on the PetStore website.

  6. The results display as follows:

    The Logs entry of the output shows the state changes from the method request to the integration request and from the integration response to the method response. This can be useful for troubleshooting any mapping errors that cause the request to fail. In this example, no mapping is applied: the method request is identical to the integration request and the integration response is the same as the method response.

    To test the API using a client other than the API Gateway test-invoke-request feature, you must first deploy the API to a stage.

  7. To deploy the sample API, select the PetStore API and the root / resource, and then choose Deploy API from the Actions menu.

    In Deploy API, for Deployment stage, choose [New Stage] because this is the first deployment of the API. Type a name (e.g., test) in Stage name and, optionally, type descriptions in Stage description and Deployment description. Choose Deploy.

    In the resulting Stage Editor pane, Invoke URL displays the URL to invoke the API's GET / method request.

  8. On Stage Editor, follow the Invoke URL link to submit the GET / method request in a browser. The result, generated from the mapping template in the integration response, is shown as follows:

  9. In the Stages navigation pane, expand the test stage, select GET on /pets/{petId}, and then copy the Invoke URL value of{petId}. {petId} stands for a path variable.

    Paste the Invoke URL value (obtained in the previous step) into the address bar of a browser, replacing {petId} by, for example, 1, and press Enter to submit the request. A 200 OK response should return with the following JSON payload:

    { "id": 1, "type": "dog", "price": 249.99 }

    Invoking the API method as shown is possible because its Authorization type is set to NONE. If the AWS_IAM authorization were used, you would sign the request using the Signature Version 4 protocols. For an example of such a request, see Build an API Gateway API to Expose an HTTP Endpoint.

See Also

Use API Gateway Custom Authorizers, Deploying an API

On this page: