# Tutorial: Create a REST API as an Amazon S3 proxy As an example to showcase using a REST API in API Gateway to proxy Amazon S3, this section describes how to create and configure a REST API to expose the following Amazon S3 operations: + Expose GET on the API's root resource to [list all of the Amazon S3 buckets of a caller](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html). + Expose GET on a Folder resource to [view a list of all of the objects in an Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html). + Expose GET on a Folder/Item resource to [view or download an object from an Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html). You might want to import the sample API as an Amazon S3 proxy, as shown in [OpenAPI definitions of the sample API as an Amazon S3 proxy](api-as-s3-proxy-export-swagger-with-extensions.md). This sample contains more exposed methods. For instructions on how to import an API using the OpenAPI definition, see [Develop REST APIs using OpenAPI in API Gateway](api-gateway-import-api.md). **Note** To integrate your API Gateway API with Amazon S3, you must choose a region where both the API Gateway and Amazon S3 services are available. For region availability, see [Amazon API Gateway Endpoints and Quotas](https://docs.aws.amazon.com/general/latest/gr/apigateway.html). **Topics** + [Set up IAM permissions for the API to invoke Amazon S3 actions](#api-as-s3-proxy-iam-permissions) + [Create API resources to represent Amazon S3 resources](#api-as-s3-proxy-create-resources) + [Expose an API method to list the caller's Amazon S3 buckets](#api-root-get-as-s3-get-service) + [Expose API methods to access an Amazon S3 bucket](#api-folder-operations-as-s3-bucket-actions) + [Expose API methods to access an Amazon S3 object in a bucket](#api-items-in-folder-as-s3-objects-in-bucket) + [OpenAPI definitions of the sample API as an Amazon S3 proxy](api-as-s3-proxy-export-swagger-with-extensions.md) + [Call the API using a REST API client](api-as-s3-proxy-test-using-postman.md) ## Set up IAM permissions for the API to invoke Amazon S3 actions To allow the API to invoke Amazon S3 actions, you must have the appropriate IAM policies attached to an IAM role. In this step, you create a new IAM role. **To create the AWS service proxy execution role** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. Choose **Roles**. 1. Choose **Create role**. 1. Choose **AWS service** under **Select type of trusted entity**, and then select **API Gateway** and select **Allows API Gateway to push logs to CloudWatch Logs**. 1. Choose **Next**, and then choose **Next**. 1. For **Role name**, enter **APIGatewayS3ProxyPolicy**, and then choose **Create role**. 1. In the **Roles** list, choose the role you just created. You may need to scroll or use the search bar to find the role. 1. For the selected role, select the **Add permissions** tab. 1. Choose **Attach policies** from the dropdown list. 1. In the search bar, enter **AmazonS3FullAccess** and choose **Add permissions**. **Note** This tutorial uses a managed policy for simplicity. As a best practice, you should create your own IAM policy to grant the minimum permissions required. 1. Note the newly created **Role ARN**, you will use it later. ## Create API resources to represent Amazon S3 resources You use the API's root (`/`) resource as the container of an authenticated caller's Amazon S3 buckets. You also create a `Folder` and `Item` resources to represent a particular Amazon S3 bucket and a particular Amazon S3 object, respectively. The folder name and object key will be specified, in the form of path parameters as part of a request URL, by the caller. **Note** When accessing objects whose object key includes `/` or any other special character, the character needs to be URL encoded. For example, `test/test.txt` should be encoded to `test%2Ftest.txt`. **To create an API resource that exposes the Amazon S3 service features** 1. In the same AWS Region you created your Amazon S3 bucket, create an API named **MyS3**. This API's root resource (**/**) represents the Amazon S3 service. In this step, you create two additional resources **/\$1folder\$1** and **/\$1item\$1**. 1. Choose **Create resource**. 1. Keep **Proxy resource** turned off. 1. For **Resource path**, select `/`. 1. For **Resource name**, enter **\$1folder\$1**. 1. Keep **CORS (Cross Origin Resource Sharing)** unchecked. 1. Choose **Create resource**. 1. Select the **/\$1folder\$1** resource, and then choose **Create resource**. 1. Use the previous steps to create a child resource of **/\$1folder\$1** named **\$1item\$1**. Your final API should look similar to the following: ![\[Create an API in API Gateway as an Amazon S3 proxy\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/aws_proxy_s3_create_api-resources_new_console.png) ## Expose an API method to list the caller's Amazon S3 buckets Getting the list of Amazon S3 buckets of the caller involves invoking the [GET Service](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html) action on Amazon S3. On the API's root resource, (**/**), create the GET method. Configure the GET method to integrate with the Amazon S3, as follows. **To create and initialize the API's `GET /` method** 1. Select the **/** resource, and then choose **Create method**. 1. For method type, select **GET**. 1. For **Integration type**, select **AWS service**. 1. For **AWS Region**, select the AWS Region where you created your Amazon S3 bucket. 1. For **AWS service**, select **Amazon Simple Storage Service**. 1. Keep **AWS subdomain** blank. 1. For **HTTP method**, select **GET**. 1. For **Action type**, select **Use path override**. With path override, API Gateway forwards the client request to Amazon S3 as the corresponding [Amazon S3 REST API path-style request](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAPI.html), in which a Amazon S3 resource is expressed by the resource path of the `s3-host-name/bucket/key` pattern. API Gateway sets the `s3-host-name` and passes the client specified `bucket` and `key` from the client to Amazon S3. 1. For **Path override**, enter **/**. 1. For **Execution role**, enter the role ARN for **APIGatewayS3ProxyPolicy**. 1. Choose **Method request settings**. You use the method request settings to control who can call this method of your API. 1. For **Authorization**, from the dropdown menu, select `AWS_IAM`. ![\[Declare method response types\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/aws_proxy_s3_setup_method_request_authorization_new_console.png) 1. Choose **Create method**. This setup integrates the frontend `GET https://your-api-host/stage/` request with the backend `GET https://your-s3-host/`. For your API to return successful responses and exceptions properly to the caller, you declare the 200, 400 and 500 responses in **Method response**. You use the default mapping for 200 responses so that backend responses of the status code not declared here will be returned to the caller as 200 ones. **To declare response types for the `GET /` method** 1. On the **Method response** tab, under **Response 200**, choose **Edit**. 1. Choose **Add header** and do the following: 1. For **Header name**, enter **Content-Type**. 1. Choose **Add header**. Repeat these steps to create a **Timestamp** header and a **Content-Length** header. 1. Choose **Save**. 1. On the **Method response** tab, under **Method responses**, choose **Create response**. 1. For **HTTP status code**, enter **400**. You do not set any headers for this response. 1. Choose **Save**. 1. Repeat the following steps to create the 500 response. You do not set any headers for this response. Because the successful integration response from Amazon S3 returns the bucket list as an XML payload and the default method response from API Gateway returns a JSON payload, you must map the backend Content-Type header parameter value to the frontend counterpart. Otherwise, the client will receive `application/json` for the content type when the response body is actually an XML string. The following procedure shows how to set this up. In addition, you also want to display to the client other header parameters, such as Date and Content-Length. **To set up response header mappings for the GET / method** 1. On the **Integration response** tab, under **Default - Response**, choose **Edit**. 1. For the **Content-Length** header, enter **integration.response.header.Content-Length** for the mapping value. 1. For the **Content-Type** header, enter **integration.response.header.Content-Type** for the mapping value. 1. For the **Timestamp** header, enter **integration.response.header.Date** for the mapping value. 1. Choose **Save**. The result should look similar to the following: ![\[Map integration response headers to method response headers\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/aws_proxy_s3_setup_integration_response_headers_new_console.png) 1. On the **Integration response** tab, under **Integration responses**, choose **Create response**. 1. For **HTTP status regex**, enter **4\$1d\$12\$1**. This maps all 4xx HTTP response status codes to the method response. 1. For **Method response status code**, select **400**. 1. Choose **Create**. 1. Repeat the following steps to create an integration response for the 500 method response. For **HTTP status regex**, enter **5\$1d\$12\$1**. As a good practice, you can test the API you have configured so far. **To test the `GET /` method** 1. Choose the **Test** tab. You might need to choose the right arrow button to show the tab. 1. Choose **Test**. The result should look like the following image: ![\[Test API root GET bucket result\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/aws_proxy_s3_test_root_get_result_new_console.png) ## Expose API methods to access an Amazon S3 bucket To work with an Amazon S3 bucket, you expose the `GET` method on the /\$1folder\$1 resource to list objects in a bucket. The instructions are similar to those described in [Expose an API method to list the caller's Amazon S3 buckets](#api-root-get-as-s3-get-service). For more methods, you can import the sample API here, [OpenAPI definitions of the sample API as an Amazon S3 proxy](api-as-s3-proxy-export-swagger-with-extensions.md). **To expose the GET method on a folder resource** 1. Select the **/\$1folder\$1** resource, and then choose **Create method**. 1. For method type, select **GET**. 1. For **Integration type**, select **AWS service**. 1. For **AWS Region**, select the AWS Region where you created your Amazon S3 bucket. 1. For **AWS service**, select **Amazon Simple Storage Service**. 1. Keep **AWS subdomain** blank. 1. For **HTTP method**, select **GET**. 1. For **Action type**, select **Use path override**. 1. For **Path override**, enter **\$1bucket\$1**. 1. For **Execution role**, enter the role ARN for **APIGatewayS3ProxyPolicy**. 1. Choose **Create method**. You set the `{folder}` path parameter in the Amazon S3 endpoint URL. You need to map the `{folder}` path parameter of the method request to the `{bucket}` path parameter of the integration request. **To map `{folder}` to `{bucket}`** 1. On the **Integration request** tab, under **Integration request settings**, choose **Edit**. 1. Choose **URL path parameters**, and then choose **Add path parameter**. 1. For **Name**, enter **bucket**. 1. For **Mapped from**, enter **method.request.path.folder**. 1. Choose **Save**. Now, you test your API. **To test the `/{folder} GET` method.** 1. Choose the **Test** tab. You might need to choose the right arrow button to show the tab. 1. Under **Path**, for **folder**, enter the name of your bucket. 1. Choose **Test**. The test result will contain a list of object in your bucket. ![\[Test the GET method to create an Amazon S3 bucket.\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/aws_proxy_s3_test_api_folder_get_new_console.png) ## Expose API methods to access an Amazon S3 object in a bucket Amazon S3 supports GET, DELETE, HEAD, OPTIONS, POST and PUT actions to access and manage objects in a given bucket. In this tutorial, you expose a `GET` method on the `{folder}/{item}` resource to get an image from a bucket. For more applications of the `{folder}/{item}` resource, see the sample API, [OpenAPI definitions of the sample API as an Amazon S3 proxy](api-as-s3-proxy-export-swagger-with-extensions.md). **To expose the GET method on a item resource** 1. Select the **/\$1item\$1** resource, and then choose **Create method**. 1. For method type, select **GET**. 1. For **Integration type**, select **AWS service**. 1. For **AWS Region**, select the AWS Region where you created your Amazon S3 bucket. 1. For **AWS service**, select **Amazon Simple Storage Service**. 1. Keep **AWS subdomain** blank. 1. For **HTTP method**, select **GET**. 1. For **Action type**, select **Use path override**. 1. For **Path override**, enter **\$1bucket\$1/\$1object\$1**. 1. For **Execution role**, enter the role ARN for **APIGatewayS3ProxyPolicy**. 1. Choose **Create method**. You set the `{folder}` and `{item}` path parameters in the Amazon S3 endpoint URL. You need to map the path parameter of the method request to the path parameter of the integration request. In this step, you do the following: + Map the `{folder}` path parameter of the method request to the `{bucket}` path parameter of the integration request. + Map the `{item}` path parameter of the method request to the `{object}` path parameter of the integration request. **To map `{folder}` to `{bucket}` and `{item}` to `{object}`** 1. On the **Integration request** tab, under **Integration request settings**, choose **Edit**. 1. Choose **URL path parameters**. 1. Choose **Add path parameter**. 1. For **Name**, enter **bucket**. 1. For **Mapped from**, enter **method.request.path.folder**. 1. Choose **Add path parameter**. 1. For **Name**, enter **object**. 1. For **Mapped from**, enter **method.request.path.item**. 1. Choose **Save**. **To test the `/{folder}/{object} GET` method.** 1. Choose the **Test** tab. You might need to choose the right arrow button to show the tab. 1. Under **Path**, for **folder**, enter the name of your bucket. 1. Under **Path**, for **item**, enter the name of an item. 1. Choose **Test**. The response body will contain the contents of the item. ![\[Test the GET method to create an Amazon S3 bucket.\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/aws_proxy_s3_test_api_item_get_new_console.png) The request correctly returns the plain text of ("Hello world") as the content of the specified file (test.txt) in the given Amazon S3 bucket (amzn-s3-demo-bucket). To download or upload binary files, which in API Gateway is considered any thing other than utf-8 encoded JSON content, additional API settings are necessary. This is outlined as follows: **To download or upload binary files from S3** 1. Register the media types of the affected file to the API's binaryMediaTypes. You can do this in the console: 1. Choose **API settings** for the API. 1. Under **Binary media types**, choose **Manage media types**. 1. Choose **Add binary media type**, and then enter the required media type, for example, `image/png`. 1. Choose **Save changes** to save the setting. 1. Add the `Content-Type` (for upload) and/or `Accept` (for download) header to the method request to require the client to specify the required binary media type and map them to the integration request. 1. Set **Content Handling** to `Passthrough` in the integration request (for upload) and in a integration response (for download). Make sure that no mapping template is defined for the affected content type. For more information, see [Data transformations for REST APIs in API Gateway](rest-api-data-transformations.md). The payload size limit is 10 MB. See [Quotas for configuring and running a REST API in API Gateway](api-gateway-execution-service-limits-table.md). Make sure that files on Amazon S3 have the correct content types added as the files' metadata. For streamable media content, `Content-Disposition:inline` may also need to be added to the metadata. For more information about the binary support in API Gateway, see [Content type conversions in API Gateway](api-gateway-payload-encodings-workflow.md). # OpenAPI definitions of the sample API as an Amazon S3 proxy The following OpenAPI definitions describes an API that works as an Amazon S3 proxy. This API contains more Amazon S3 operations than the API you created in the tutorial. The following methods are exposed in the OpenAPI definitions: + Expose GET on the API's root resource to [list all of the Amazon S3 buckets of a caller](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html). + Expose GET on a Folder resource to [view a list of all of the objects in an Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html). + Expose PUT on a Folder resource to [add a bucket to Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html). + Expose DELETE on a Folder resource to [remove a bucket from Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html). + Expose GET on a Folder/Item resource to [view or download an object from an Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html). + Expose PUT on a Folder/Item resource to [upload an object to an Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html). + Expose HEAD on a Folder/Item resource to [get object metadata in an Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html). + Expose DELETE on a Folder/Item resource to [remove an object from an Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html). For instructions on how to import an API using the OpenAPI definition, see [Develop REST APIs using OpenAPI in API Gateway](api-gateway-import-api.md). For instructions on how to create a similar API, see [Tutorial: Create a REST API as an Amazon S3 proxy](integrating-api-with-aws-services-s3.md). To learn how to invoke this API using [Postman](https://www.postman.com/), which supports the AWS IAM authorization, see [Call the API using a REST API client](api-as-s3-proxy-test-using-postman.md). ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-10-13T23:04:43Z", "title": "MyS3" }, "host": "9gn28ca086.execute-api.{region}.amazonaws.com", "basePath": "/S3", "schemes": [ "https" ], "paths": { "/": { "get": { "produces": [ "application/json" ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" }, "headers": { "Content-Length": { "type": "string" }, "Timestamp": { "type": "string" }, "Content-Type": { "type": "string" } } }, "400": { "description": "400 response" }, "500": { "description": "500 response" } }, "security": [ { "sigv4": [] } ], "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole", "responses": { "4\\d{2}": { "statusCode": "400" }, "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "integration.response.header.Content-Type", "method.response.header.Content-Length": "integration.response.header.Content-Length", "method.response.header.Timestamp": "integration.response.header.Date" } }, "5\\d{2}": { "statusCode": "500" } }, "uri": "arn:aws:apigateway:us-west-2:s3:path//", "passthroughBehavior": "when_no_match", "httpMethod": "GET", "type": "aws" } } }, "/{folder}": { "get": { "produces": [ "application/json" ], "parameters": [ { "name": "folder", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" }, "headers": { "Content-Length": { "type": "string" }, "Date": { "type": "string" }, "Content-Type": { "type": "string" } } }, "400": { "description": "400 response" }, "500": { "description": "500 response" } }, "security": [ { "sigv4": [] } ], "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole", "responses": { "4\\d{2}": { "statusCode": "400" }, "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "integration.response.header.Content-Type", "method.response.header.Date": "integration.response.header.Date", "method.response.header.Content-Length": "integration.response.header.content-length" } }, "5\\d{2}": { "statusCode": "500" } }, "requestParameters": { "integration.request.path.bucket": "method.request.path.folder" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}", "passthroughBehavior": "when_no_match", "httpMethod": "GET", "type": "aws" } }, "put": { "produces": [ "application/json" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": false, "type": "string" }, { "name": "folder", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" }, "headers": { "Content-Length": { "type": "string" }, "Content-Type": { "type": "string" } } }, "400": { "description": "400 response" }, "500": { "description": "500 response" } }, "security": [ { "sigv4": [] } ], "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole", "responses": { "4\\d{2}": { "statusCode": "400" }, "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "integration.response.header.Content-Type", "method.response.header.Content-Length": "integration.response.header.Content-Length" } }, "5\\d{2}": { "statusCode": "500" } }, "requestParameters": { "integration.request.path.bucket": "method.request.path.folder", "integration.request.header.Content-Type": "method.request.header.Content-Type" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}", "passthroughBehavior": "when_no_match", "httpMethod": "PUT", "type": "aws" } }, "delete": { "produces": [ "application/json" ], "parameters": [ { "name": "folder", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" }, "headers": { "Date": { "type": "string" }, "Content-Type": { "type": "string" } } }, "400": { "description": "400 response" }, "500": { "description": "500 response" } }, "security": [ { "sigv4": [] } ], "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole", "responses": { "4\\d{2}": { "statusCode": "400" }, "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "integration.response.header.Content-Type", "method.response.header.Date": "integration.response.header.Date" } }, "5\\d{2}": { "statusCode": "500" } }, "requestParameters": { "integration.request.path.bucket": "method.request.path.folder" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}", "passthroughBehavior": "when_no_match", "httpMethod": "DELETE", "type": "aws" } } }, "/{folder}/{item}": { "get": { "produces": [ "application/json" ], "parameters": [ { "name": "item", "in": "path", "required": true, "type": "string" }, { "name": "folder", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" }, "headers": { "content-type": { "type": "string" }, "Content-Type": { "type": "string" } } }, "400": { "description": "400 response" }, "500": { "description": "500 response" } }, "security": [ { "sigv4": [] } ], "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole", "responses": { "4\\d{2}": { "statusCode": "400" }, "default": { "statusCode": "200", "responseParameters": { "method.response.header.content-type": "integration.response.header.content-type", "method.response.header.Content-Type": "integration.response.header.Content-Type" } }, "5\\d{2}": { "statusCode": "500" } }, "requestParameters": { "integration.request.path.object": "method.request.path.item", "integration.request.path.bucket": "method.request.path.folder" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}", "passthroughBehavior": "when_no_match", "httpMethod": "GET", "type": "aws" } }, "head": { "produces": [ "application/json" ], "parameters": [ { "name": "item", "in": "path", "required": true, "type": "string" }, { "name": "folder", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" }, "headers": { "Content-Length": { "type": "string" }, "Content-Type": { "type": "string" } } }, "400": { "description": "400 response" }, "500": { "description": "500 response" } }, "security": [ { "sigv4": [] } ], "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole", "responses": { "4\\d{2}": { "statusCode": "400" }, "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "integration.response.header.Content-Type", "method.response.header.Content-Length": "integration.response.header.Content-Length" } }, "5\\d{2}": { "statusCode": "500" } }, "requestParameters": { "integration.request.path.object": "method.request.path.item", "integration.request.path.bucket": "method.request.path.folder" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}", "passthroughBehavior": "when_no_match", "httpMethod": "HEAD", "type": "aws" } }, "put": { "produces": [ "application/json" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": false, "type": "string" }, { "name": "item", "in": "path", "required": true, "type": "string" }, { "name": "folder", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" }, "headers": { "Content-Length": { "type": "string" }, "Content-Type": { "type": "string" } } }, "400": { "description": "400 response" }, "500": { "description": "500 response" } }, "security": [ { "sigv4": [] } ], "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole", "responses": { "4\\d{2}": { "statusCode": "400" }, "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "integration.response.header.Content-Type", "method.response.header.Content-Length": "integration.response.header.Content-Length" } }, "5\\d{2}": { "statusCode": "500" } }, "requestParameters": { "integration.request.path.object": "method.request.path.item", "integration.request.path.bucket": "method.request.path.folder", "integration.request.header.Content-Type": "method.request.header.Content-Type" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}", "passthroughBehavior": "when_no_match", "httpMethod": "PUT", "type": "aws" } }, "delete": { "produces": [ "application/json" ], "parameters": [ { "name": "item", "in": "path", "required": true, "type": "string" }, { "name": "folder", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" }, "headers": { "Content-Length": { "type": "string" }, "Content-Type": { "type": "string" } } }, "400": { "description": "400 response" }, "500": { "description": "500 response" } }, "security": [ { "sigv4": [] } ], "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole", "responses": { "4\\d{2}": { "statusCode": "400" }, "default": { "statusCode": "200" }, "5\\d{2}": { "statusCode": "500" } }, "requestParameters": { "integration.request.path.object": "method.request.path.item", "integration.request.path.bucket": "method.request.path.folder" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}", "passthroughBehavior": "when_no_match", "httpMethod": "DELETE", "type": "aws" } } } }, "securityDefinitions": { "sigv4": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "awsSigv4" } }, "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } } ``` ------ #### [ OpenAPI 3.0 ] ``` { "openapi" : "3.0.1", "info" : { "title" : "MyS3", "version" : "2016-10-13T23:04:43Z" }, "servers" : [ { "url" : "https://9gn28ca086.execute-api.{region}.amazonaws.com/{basePath}", "variables" : { "basePath" : { "default" : "S3" } } } ], "paths" : { "/{folder}" : { "get" : { "parameters" : [ { "name" : "folder", "in" : "path", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "400" : { "description" : "400 response", "content" : { } }, "500" : { "description" : "500 response", "content" : { } }, "200" : { "description" : "200 response", "headers" : { "Content-Length" : { "schema" : { "type" : "string" } }, "Date" : { "schema" : { "type" : "string" } }, "Content-Type" : { "schema" : { "type" : "string" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Empty" } } } } }, "x-amazon-apigateway-integration" : { "credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole", "httpMethod" : "GET", "uri" : "arn:aws:apigateway:us-west-2:s3:path/{bucket}", "responses" : { "4\\d{2}" : { "statusCode" : "400" }, "default" : { "statusCode" : "200", "responseParameters" : { "method.response.header.Content-Type" : "integration.response.header.Content-Type", "method.response.header.Date" : "integration.response.header.Date", "method.response.header.Content-Length" : "integration.response.header.content-length" } }, "5\\d{2}" : { "statusCode" : "500" } }, "requestParameters" : { "integration.request.path.bucket" : "method.request.path.folder" }, "passthroughBehavior" : "when_no_match", "type" : "aws" } }, "put" : { "parameters" : [ { "name" : "Content-Type", "in" : "header", "schema" : { "type" : "string" } }, { "name" : "folder", "in" : "path", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "400" : { "description" : "400 response", "content" : { } }, "500" : { "description" : "500 response", "content" : { } }, "200" : { "description" : "200 response", "headers" : { "Content-Length" : { "schema" : { "type" : "string" } }, "Content-Type" : { "schema" : { "type" : "string" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Empty" } } } } }, "x-amazon-apigateway-integration" : { "credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole", "httpMethod" : "PUT", "uri" : "arn:aws:apigateway:us-west-2:s3:path/{bucket}", "responses" : { "4\\d{2}" : { "statusCode" : "400" }, "default" : { "statusCode" : "200", "responseParameters" : { "method.response.header.Content-Type" : "integration.response.header.Content-Type", "method.response.header.Content-Length" : "integration.response.header.Content-Length" } }, "5\\d{2}" : { "statusCode" : "500" } }, "requestParameters" : { "integration.request.path.bucket" : "method.request.path.folder", "integration.request.header.Content-Type" : "method.request.header.Content-Type" }, "passthroughBehavior" : "when_no_match", "type" : "aws" } }, "delete" : { "parameters" : [ { "name" : "folder", "in" : "path", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "400" : { "description" : "400 response", "content" : { } }, "500" : { "description" : "500 response", "content" : { } }, "200" : { "description" : "200 response", "headers" : { "Date" : { "schema" : { "type" : "string" } }, "Content-Type" : { "schema" : { "type" : "string" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Empty" } } } } }, "x-amazon-apigateway-integration" : { "credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole", "httpMethod" : "DELETE", "uri" : "arn:aws:apigateway:us-west-2:s3:path/{bucket}", "responses" : { "4\\d{2}" : { "statusCode" : "400" }, "default" : { "statusCode" : "200", "responseParameters" : { "method.response.header.Content-Type" : "integration.response.header.Content-Type", "method.response.header.Date" : "integration.response.header.Date" } }, "5\\d{2}" : { "statusCode" : "500" } }, "requestParameters" : { "integration.request.path.bucket" : "method.request.path.folder" }, "passthroughBehavior" : "when_no_match", "type" : "aws" } } }, "/{folder}/{item}" : { "get" : { "parameters" : [ { "name" : "item", "in" : "path", "required" : true, "schema" : { "type" : "string" } }, { "name" : "folder", "in" : "path", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "400" : { "description" : "400 response", "content" : { } }, "500" : { "description" : "500 response", "content" : { } }, "200" : { "description" : "200 response", "headers" : { "content-type" : { "schema" : { "type" : "string" } }, "Content-Type" : { "schema" : { "type" : "string" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Empty" } } } } }, "x-amazon-apigateway-integration" : { "credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole", "httpMethod" : "GET", "uri" : "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}", "responses" : { "4\\d{2}" : { "statusCode" : "400" }, "default" : { "statusCode" : "200", "responseParameters" : { "method.response.header.content-type" : "integration.response.header.content-type", "method.response.header.Content-Type" : "integration.response.header.Content-Type" } }, "5\\d{2}" : { "statusCode" : "500" } }, "requestParameters" : { "integration.request.path.object" : "method.request.path.item", "integration.request.path.bucket" : "method.request.path.folder" }, "passthroughBehavior" : "when_no_match", "type" : "aws" } }, "put" : { "parameters" : [ { "name" : "Content-Type", "in" : "header", "schema" : { "type" : "string" } }, { "name" : "item", "in" : "path", "required" : true, "schema" : { "type" : "string" } }, { "name" : "folder", "in" : "path", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "400" : { "description" : "400 response", "content" : { } }, "500" : { "description" : "500 response", "content" : { } }, "200" : { "description" : "200 response", "headers" : { "Content-Length" : { "schema" : { "type" : "string" } }, "Content-Type" : { "schema" : { "type" : "string" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Empty" } } } } }, "x-amazon-apigateway-integration" : { "credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole", "httpMethod" : "PUT", "uri" : "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}", "responses" : { "4\\d{2}" : { "statusCode" : "400" }, "default" : { "statusCode" : "200", "responseParameters" : { "method.response.header.Content-Type" : "integration.response.header.Content-Type", "method.response.header.Content-Length" : "integration.response.header.Content-Length" } }, "5\\d{2}" : { "statusCode" : "500" } }, "requestParameters" : { "integration.request.path.object" : "method.request.path.item", "integration.request.path.bucket" : "method.request.path.folder", "integration.request.header.Content-Type" : "method.request.header.Content-Type" }, "passthroughBehavior" : "when_no_match", "type" : "aws" } }, "delete" : { "parameters" : [ { "name" : "item", "in" : "path", "required" : true, "schema" : { "type" : "string" } }, { "name" : "folder", "in" : "path", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "400" : { "description" : "400 response", "content" : { } }, "500" : { "description" : "500 response", "content" : { } }, "200" : { "description" : "200 response", "headers" : { "Content-Length" : { "schema" : { "type" : "string" } }, "Content-Type" : { "schema" : { "type" : "string" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Empty" } } } } }, "x-amazon-apigateway-integration" : { "credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole", "httpMethod" : "DELETE", "uri" : "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}", "responses" : { "4\\d{2}" : { "statusCode" : "400" }, "default" : { "statusCode" : "200" }, "5\\d{2}" : { "statusCode" : "500" } }, "requestParameters" : { "integration.request.path.object" : "method.request.path.item", "integration.request.path.bucket" : "method.request.path.folder" }, "passthroughBehavior" : "when_no_match", "type" : "aws" } }, "head" : { "parameters" : [ { "name" : "item", "in" : "path", "required" : true, "schema" : { "type" : "string" } }, { "name" : "folder", "in" : "path", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "400" : { "description" : "400 response", "content" : { } }, "500" : { "description" : "500 response", "content" : { } }, "200" : { "description" : "200 response", "headers" : { "Content-Length" : { "schema" : { "type" : "string" } }, "Content-Type" : { "schema" : { "type" : "string" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Empty" } } } } }, "x-amazon-apigateway-integration" : { "credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole", "httpMethod" : "HEAD", "uri" : "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}", "responses" : { "4\\d{2}" : { "statusCode" : "400" }, "default" : { "statusCode" : "200", "responseParameters" : { "method.response.header.Content-Type" : "integration.response.header.Content-Type", "method.response.header.Content-Length" : "integration.response.header.Content-Length" } }, "5\\d{2}" : { "statusCode" : "500" } }, "requestParameters" : { "integration.request.path.object" : "method.request.path.item", "integration.request.path.bucket" : "method.request.path.folder" }, "passthroughBehavior" : "when_no_match", "type" : "aws" } } }, "/" : { "get" : { "responses" : { "400" : { "description" : "400 response", "content" : { } }, "500" : { "description" : "500 response", "content" : { } }, "200" : { "description" : "200 response", "headers" : { "Content-Length" : { "schema" : { "type" : "string" } }, "Timestamp" : { "schema" : { "type" : "string" } }, "Content-Type" : { "schema" : { "type" : "string" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Empty" } } } } }, "x-amazon-apigateway-integration" : { "credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole", "httpMethod" : "GET", "uri" : "arn:aws:apigateway:us-west-2:s3:path//", "responses" : { "4\\d{2}" : { "statusCode" : "400" }, "default" : { "statusCode" : "200", "responseParameters" : { "method.response.header.Content-Type" : "integration.response.header.Content-Type", "method.response.header.Content-Length" : "integration.response.header.Content-Length", "method.response.header.Timestamp" : "integration.response.header.Date" } }, "5\\d{2}" : { "statusCode" : "500" } }, "passthroughBehavior" : "when_no_match", "type" : "aws" } } } }, "components" : { "schemas" : { "Empty" : { "title" : "Empty Schema", "type" : "object" } } } } ``` ------ # Call the API using a REST API client To provide an end-to-end tutorial, we now show how to call the API using [Postman](https://www.postman.com/), which supports the AWS IAM authorization. **To call our Amazon S3 proxy API using Postman** 1. Deploy or redeploy the API. Make a note of the base URL of the API that is displayed next to **Invoke URL** at the top of the **Stage Editor**. 1. Launch Postman. 1. Choose **Authorization** and then choose `AWS Signature`. Enter your IAM user's Access Key ID and Secret Access Key into the **AccessKey** and **SecretKey**input fields, respectively. Enter the AWS Region to which your API is deployed in the **AWS Region** text box. Enter `execute-api` in the **Service Name** input field. You can create a pair of the keys from the **Security Credentials** tab from your IAM user account in the IAM Management Console. 1. To add a bucket named `amzn-s3-demo-bucket` to your Amazon S3 account in the `{region}` region: 1. Choose **PUT** from the drop-down method list and type the method URL (`https://api-id.execute-api.aws-region.amazonaws.com/stage/folder-name` 1. Set the `Content-Type` header value as `application/xml`. You may need to delete any existing headers before setting the content type. 1. Choose **Body** menu item and type the following XML fragment as the request body: ``` {region} ``` 1. Choose **Send** to submit the request. If successful, you should receive a `200 OK` response with an empty payload. 1. To add a text file to a bucket, follow the instructions above. If you specify a bucket name of **amzn-s3-demo-bucket** for `{folder}` and a file name of **Readme.txt** for `{item}` in the URL and provide a text string of **Hello, World\$1** as the file contents (thereby making it the request payload), the request becomes ``` PUT /S3/amzn-s3-demo-bucket/Readme.txt HTTP/1.1 Host: 9gn28ca086.execute-api.{region}.amazonaws.com Content-Type: application/xml X-Amz-Date: 20161015T062647Z Authorization: AWS4-HMAC-SHA256 Credential=access-key-id/20161015/{region}/execute-api/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=ccadb877bdb0d395ca38cc47e18a0d76bb5eaf17007d11e40bf6fb63d28c705b Cache-Control: no-cache Postman-Token: 6135d315-9cc4-8af8-1757-90871d00847e Hello, World! ``` If everything goes well, you should receive a `200 OK` response with an empty payload. 1. To get the content of the `Readme.txt` file we just added to the `amzn-s3-demo-bucket` bucket, do a GET request like the following one: ``` GET /S3/amzn-s3-demo-bucket/Readme.txt HTTP/1.1 Host: 9gn28ca086.execute-api.{region}.amazonaws.com Content-Type: application/xml X-Amz-Date: 20161015T063759Z Authorization: AWS4-HMAC-SHA256 Credential=access-key-id/20161015/{region}/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=ba09b72b585acf0e578e6ad02555c00e24b420b59025bc7bb8d3f7aed1471339 Cache-Control: no-cache Postman-Token: d60fcb59-d335-52f7-0025-5bd96928098a ``` If successful, you should receive a `200 OK` response with the `Hello, World!` text string as the payload. 1. To list items in the `amzn-s3-demo-bucket` bucket, submit the following request: ``` GET /S3/amzn-s3-demo-bucket HTTP/1.1 Host: 9gn28ca086.execute-api.{region}.amazonaws.com Content-Type: application/xml X-Amz-Date: 20161015T064324Z Authorization: AWS4-HMAC-SHA256 Credential=access-key-id/20161015/{region}/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=4ac9bd4574a14e01568134fd16814534d9951649d3a22b3b0db9f1f5cd4dd0ac Cache-Control: no-cache Postman-Token: 9c43020a-966f-61e1-81af-4c49ad8d1392 ``` If successful, you should receive a `200 OK` response with an XML payload showing a single item in the specified bucket, unless you added more files to the bucket before submitting this request. ``` apig-demo-5 1000 false Readme.txt 2016-10-15T06:26:48.000Z "65a8e27d8879283831b664bd8b7f0ad4" 13 06e4b09e9d...603addd12ee user-name STANDARD ``` **Note** To upload or download an image, you need to set content handling to CONVERT\$1TO\$1BINARY.