How do I upload an image or PDF file to Amazon S3 through API Gateway?

Short description

To use API Gateway to upload an image or PDF as a binary file to an Amazon S3 bucket, activate binary support.

To grant API Gateway access to your S3 bucket, create an AWS Identity and Access Management (IAM) role. The IAM role must include permissions for API Gateway to perform the PutObject and GetObject actions on your S3 bucket.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Create an IAM role for API Gateway

Complete the following steps:

1. Open the IAM console.
2. In the navigation pane, choose Roles.
3. Choose Create role.
4. In the Select trusted entity type section, choose AWS service.
5. In the Service or use case section, choose API Gateway.
6. In the Use case section, choose API Gateway.
7. Choose Next.
8. For Role name, enter a name for your policy. For example, enter api-gateway-upload-to-s3.
9. (Optional) Add tags to the IAM role.
10. Choose Create role.

Create and attach an IAM policy to the API Gateway role

Complete the following steps:

1. Open the IAM console.
2. In the navigation pane, choose Roles.
3. In the search box, enter the name of the IAM role for the API Gateway, and then select the role from the Role name column.
4. On the Roles detail page tab, choose Add permissions.
5. Choose Create inline policy.
6. On the Visual editor tab, in the Select a service section, choose Choose a service.
7. Enter S3, and then choose S3.
8. In the Specify actions from the service to be allowed box, enter PutObject, and then choose PutObject.
9. Enter GetObject, and then choose GetObject.
10. Expand Resources, and then choose Specific.
11. Choose Add ARN.
12. For Resource bucket name, enter the name of your bucket. Include the prefix if applicable.
13. For Resource object name, enter an object name.
    Note: The bucket name specifies the location of the uploaded files. The object name specifies the pattern that the object must adhere to for policy alignment. For more information, see General purpose bucket naming rules and Amazon S3 objects overview.
14. Choose Add ARNs.
15. Choose Next.
16. For Name, enter the name of your policy.
17. Choose Create policy.

Create an API Gateway REST API

To create an API to deliver your requests, complete the following steps:

1. Open the API Gateway console.
2. In the navigation pane, choose APIs.
3. Choose Create API.
4. In the Choose an API type section, for REST API, choose Build.
5. For API Name, enter a name for your API, and then choose Create API.

To create resources for your API, complete the following steps:

1. In the Resources panel of your API page, select /.
2. Choose Create Resource.
3. For Resource path, choose /.
4. For Resource Path, enter {folder}.
5. Choose Create resource.
6. In the Resources panel, select the /{folder} resource.
7. Choose Create resource.
8. For Resource path, choose /{folder}/.
9. For Resource name, enter {object}.
10. Choose Create resource.

To create a PUT method for your API to upload images or PDF files, complete the following steps:

1. In the Methods section, choose Create method.
2. For Method type, choose PUT.
3. Under the Integration type category, choose AWS Service.
4. For AWS Region, choose us-east-1 or the AWS Region that's on the Bucket properties page.
5. For AWS Service, choose Simple Storage Service (S3).
6. Keep AWS Subdomain empty.
7. For HTTP method, choose PUT.
8. For Action type, choose Use path override.
9. For Path override (optional), enter {bucket}/{key}.
10. For Execution role, enter the ARN for the IAM role.
11. For Content handling, choose Passthrough.
12. Choose Create method.

Configure parameter mappings for the PUT method

Complete the following steps:

1. In the Resources panel of your API page, choose PUT.
2. Choose Integration Request, and then choose Edit.
3. Expand URL path parameters.
4. Choose Add path parameter.
5. For Name, enter bucket.
6. For Mapped from, enter method.request.path.folder.
7. Repeat steps 4–6:
   For step 5, set Name to key.
   For step 6, set Mapped from to method.request.path.object.
8. Choose Save.

Create a GET method for your API to retrieve an image

Complete the following steps:

1. In the Resources panel of your API page, choose /{object}.
2. In the Methods section, choose Create method.
3. For Method type, choose GET.
4. Under the Integration type category, choose AWS Service.
5. For AWS Region, choose us-east-1 or the Region that's on the Bucket properties page.
6. For AWS Service, choose Simple Storage Service (S3).
7. Keep AWS Subdomain empty.
8. For HTTP method, choose GET.
9. For Action type, choose Use path override.
10. For Path override (optional), enter {bucket}/{key}.
11. For Execution role, enter the ARN for the IAM role.
12. For Content Handling, choose Passthrough.
13. Choose Create method.

Configure parameter mappings for the GET method

Complete the following steps:

1. In the Resources panel of your API page, choose GET.
2. Choose Integration request, and then choose Edit.
3. Expand URL Path parameters.
4. Choose Add path parameters.
5. For Name, enter bucket.
6. For Mapped from, enter method.request.path.folder.
7. Repeat steps 4–6:
   For step 5, set Name to key.
   For step 6, set Mapped from to method.request.path.object.
8. Choose Save.

Set up response mapping to see the image or PDF in browser

Complete the following steps:

1. In the Resources panel of your API page, choose GET.
2. Choose Method response.
3. For Response 200, choose Edit.
4. Under Response body, remove application/json.
5. Under Header name, choose Add header.
6. For Name, enter content-type.
7. Choose Save.
8. Choose Integration response, and then choose Edit.
9. For Method response status code 200, enter image/jpeg for an image file or application/pdf for a PDF file.
10. Choose Save.

Set up binary media types for the API

Complete the following steps:

1. In the navigation pane of your API page, choose API settings.
2. In the Binary media types section, choose Manage media types.
3. Choose Add binary media type, and then add the / string in the text box.
   Note: Don't put the string in quotes. You can substitute a wildcard for a specific Multipurpose Internet Mail Extensions (MIME) type to manage as a binary media type. For example, to have API Gateway manage JPEG images as binary media types, choose image/jpeg. If you add */*, then API Gateway manages all media types as binary media types.
4. Choose Save changes.

Resolve CORS error with binary settings for API

Note: If you use the PUT and GET APIs in a web application, then you might get a CORS error. For more information, see CORS errors on the Mozilla website.

To resolve the CORS error with binary settings turned on, complete the following steps:

1. Open the API Gateway console.

2. Select your API.

3. Activate CORS.

4. In the Resources panel of your API page, select /{object}.

5. Choose Enable CORS.

6. Choose Default 4xx, Default 5xx for Gateway responses, and then choose GET, PUT for Access-Control-Allow-Methods.

7. Choose Save.

8. Run the following update-integration command:

   aws apigateway update-integration --rest-api-id API_ID --resource-id RESOURCE_id --http-method OPTIONS --patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT' --region AWS_REGION

   Note: Replace rest-api-id with your REST API ID, RESOURCE_id with your resource ID, and AWS_REGION with your Region. For API Gateway to run options requests, the update-integration and update-integration-response commands must be run one after the other.

9. Run the following update-integration-response command:

   aws apigateway update-integration-response --rest-api-id API_ID --resource-id RESOURCE_id --http-method OPTIONS --status-code 200 --patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT' --region AWS_REGION

   Note: Replace rest-api-id with your REST API ID, RESOURCE_id with your resource ID, and AWS_REGION with your Region.

Deploy your API

Complete the following steps:

1. In the navigation pane on your API page, choose Resources.
2. Choose Deploy API.
3. In the Deploy API window, for Stage, choose [New Stage].
4. For Stage name, enter v1.
5. Choose Deploy.
6. In the navigation pane, choose Stages.
7. Choose the v1 stage.
8. Note the invoke URL that appears.

For more information, see Deploy REST APIs in API Gateway.

Invoke your REST API to upload an image file to S3

Complete the following steps:

1. Add the bucket name and object's file name to your API's invoke URL.
2. Use your preferred client to make a PUT HTTP request. For example, you can download and use Postman on the Postman website.
3. Choose Body, and then choose binary. When the Select file button appears, select a local file to upload.

The following is an example curl command that you can run to make a PUT HTTP request to upload an image or PDF:

curl -i --location --request PUT 'https://abc12345.execute-api.us-west-2.amazonaws.com/v1/testfolder/testimage.jpeg' --header 'Content-Type: text/plain' --data-binary '@/Path/to/file/image.jpeg'

Note: Replace abc12345 with your API ID, testfolder with your S3 bucket, and testimage.jpeg with the local file that you upload.

If */* is included in the binary media types list, then you can make a PUT request to upload the file. If image.jpeg is included in the binary media types list, then add Content-Type header to your PUT request, and set it to image/jpeg. Because the web browser makes a GET request, you can view the image or PDF in a web browser with the same URL.

Related information

Enabling binary support using the API Gateway REST API