Menu
Amazon API Gateway
Developer Guide

Create an API with the API Gateway REST API

To create an API using the API Gateway REST API, you work with the RestApi, Resource, Method, MethodResponse, Integration, and IntegrationResponse entities. The following procedures show how to work with these API entities to create the simple PetStore API.

To create the simple PetStore API

  1. To create the RestApi for the API, call the restapi:create action, as shown in the following:

    Copy
    POST /restapis HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170511T214723Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170511/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=d0abd98a2a06199531c2916b162ede9f63a247032cdc8e4d077216446d13103c Cache-Control: no-cache Postman-Token: 0889d2b5-e507-6aab-f222-ab9548dbacaa { "name": "Simple PetStore (REST API)", "description": "A sample API Gateway API created using the REST API." }

    If successful, a 201 Created response is returned with a payload similar to the following:

    Copy
    { "createdDate": "2017-05-11T21:47:24Z", "description": "A sample API Gateway API created using the REST API.", "id": "x7hyqq0ik7", "name": "Simple PetStore (REST API)" }

    Note the id value of the newly created RestApi. You use this value in subsequent operations on this API. A newly created RestApi comes with the root resource (/) of the API. You need to specify the id value of this root resource to append a child resource, and to add a method on the root resource or on a child resource. To get this identifier, follow the next step.

  2. To get the root resource identifier, call restapi:resources action, as shown in the following:

    Copy
    GET /restapis/x7hyqq0ik7/resources HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170511T215738Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170511/us-west-2/apigateway/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=76c24ef91d835b85313142bf75545c4ac4c212067e8188ee6a127c21dae09e29 Cache-Control: no-cache Postman-Token: ed8fb586-8d67-8db7-d229-5a88b4620037

    If the request is successful, a 200 OK response is returned with a payload similar to the following:

    Copy
    { "_embedded": { "item": { "_links": { "self": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd" }, "method:by-http-method": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/{http_method}", "templated": true }, "method:put": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/{http_method}", "templated": true }, "resource:create-child": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd" }, "resource:update": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd" } }, "id": "0f72nvvnkd", "path": "/" } } }

    Note that the root resource is identified by the / path in the returned response payload.

  3. To add a GET method to the root resource, call the method:put action, as shown in the following:

    Copy
    PUT /restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T000729Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=8a7093411c97b0aa90f4b1890475d93cf20aa3732089da61e6deb410fbc6037d Cache-Control: no-cache Postman-Token: 48abcd2f-c357-9e44-669e-d8d813f876ca { "authorizationType": "NONE" }

    Setting the authorizationType to NONE makes the API callable by anyone. This is consistent with the access permissions on the backend PetStore website. For other backends or for other application scenarios you may need to use a different authorization type.

    The successful request returns a 201 Created response with a payload similar to the following:

    Copy
    { "_links": { "curies": [ ... ], "self": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET", "name": "GET", "title": "GET" }, "integration:put": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/integration" }, "method:delete": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET" }, "method:update": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET" }, "methodresponse:put": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/responses/{status_code}", "templated": true } }, "apiKeyRequired": false, "authorizationType": "NONE", "httpMethod": "GET" }

    The Method resource that was just created represents the client-facing method request. Depending on API requirements, you can set up header, path, and query parameters on a method request. For POST, PUT, PATCH, and other methods taking payloads, you can define a model for the payload in the method request. For more information about these settings, see Set up Method and Integration.

  4. To set up the 200 OK response for the GET / method, call the method:put action, as shown in the following:

    Copy
    PUT /restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/responses/200 HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T003943Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=229ef4cfba4bbe41132f36c027f0ae4449bb741671875075a4b216e9b778233e Cache-Control: no-cache Postman-Token: 268fcf18-92e4-dfea-821a-ebf4e1d0edfd {}

    The successful response returns a 201 Created status code and a payload similar to the following:

    Copy
    { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-method-response-{rel}.html", "name": "methodresponse", "templated": true }, "self": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/responses/200", "title": "200" }, "methodresponse:delete": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/responses/200" }, "methodresponse:update": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/responses/200" } }, "statusCode": "200" }

    The Method request and MethodRepsonse represent the client-facing interface of the GET / method of the API. For the interface to function properly, we set up its Integration and IntegrationResponse to forward the incoming request from the client to the backend, and to route the returning response from the backend to the client.

  5. To set up the Integration request with the PetStore backend, call the integration:put action, as shown in the following:

    Copy
    PUT /restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/integration HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T002249Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=10359971a8c54862a47e39d6a6e4b6e62c263e9a2b785b47b40c426c0aa61c19 Cache-Control: no-cache Postman-Token: 7f7bbb22-afdb-09ed-e22a-8c13f8e91ee7 { "type" : "HTTP", "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets" }

    In the request payload, uri points to the backend endpoint associated with the method. The type refers to the integration type. For the specified HTTP uri, the value of type must be HTTP. The httpMethod property sets the HTTP verb as required by the backend, which may be different from the method request HTTP verb set in the integration:put action URL.

    The successful response returns a 201 Created status code with a payload similar to the following:

    Copy
    { "_links": { "curies": [ ... ], "self": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/integration" }, "integration:delete": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/integration" }, "integration:update": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/integration" }, "integrationresponse:put": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/integration/responses/{status_code}", "templated": true } }, "cacheKeyParameters": [], "cacheNamespace": "0f72nvvnkd", "httpMethod": "GET", "passthroughBehavior": "WHEN_NO_MATCH", "type": "HTTP", "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets" }
  6. To set up the IntegrationResponse, call the integrationresponse:put action, as shown in the following:

    Copy
    PUT /restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/integration/responses/200 HTTP/1.1 Host: apigateway.us-west-2.amazonaws.com Content-Type: application/x-amz-json-1.0 X-Amz-Date: 20170512T004542Z Authorization: AWS4-HMAC-SHA256 Credential={ACCESS-KEY-ID}/20170512/us-west-2/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=545ab6ea151f72c52161ee856ee621f136d717e40a02743cd8fe3638895794b1 Cache-Control: no-cache Postman-Token: d29cabea-5232-7021-88ad-f1e950f55a99 {}

    The successful response returns the 201 Created status code with a payload similar to the following:

    Copy
    { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-integration-response-{rel}.html", "name": "integrationresponse", "templated": true }, "self": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/integration/responses/200", "title": "200" }, "integrationresponse:delete": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/integration/responses/200" }, "integrationresponse:update": { "href": "/restapis/x7hyqq0ik7/resources/0f72nvvnkd/methods/GET/integration/responses/200" } }, "statusCode": "200" }

    We now have successfully created a simple PetStore API.

After deploying the API to, for example, a test stage (see deployment:create), you can test this API by typing the https://x7hyqq0ik7.execute-api.us-west-2.amazonaws.com/test URL in a browser. Substitute the RestApi identifier (x7hyqq0ik7) with the identifier of your API. The expected output should be as follows:

Copy
[ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]