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

9 minute read

I want to upload an image or PDF file to Amazon Simple Storage Service (Amazon S3) through Amazon API Gateway. I also want to retrieve an image or PDF file. How do I perform these actions?

Short description

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

To grant your API 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

Create an IAM role for API Gateway

1. Open the IAM console.

2. In the navigation pane, choose Roles.

3. Choose Create role.

4. In the Select type of trusted entity section, choose AWS service.

5. In the Choose a use case section, choose API Gateway.

6. In the Select your use case section, choose API Gateway.

7. Choose Next: Permissions.

Note: This section shows the AWS managed service that permits API Gateway to push logs to a user's account. You'll add permissions for Amazon S3 later. Choose Next: Tags for now.

8. Add tags (optionally), and then choose Next: Review.

9. For Role name, enter a name for your policy. For example: api-gateway-upload-to-s3.

10. Choose Create role.

Create and attach an IAM policy to the API Gateway role

1. Open the IAM console.

2. In the navigation pane, choose Roles.

3. In the search box, enter the name of the new API Gateway role that you created. Then, choose that 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 the actions allowed in S3 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 Bucket name, enter the name of your bucket. Include the prefix, if applicable.

13. For 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 Bucket naming rules and Amazon S3 objects overview.

14. Choose Add.

15. Choose Next: Tags, add tags (optionally), and then choose Next: Review.

16. For Name, enter the name of your policy.

17. Choose Create policy.

18. In the policy search box, enter the name of the policy that you created in step 17, and then select that policy.

19. Choose Policy actions, and then choose Attach. A list of IAM roles appears.

20. Search for the API Gateway role that you created earlier. Then, select the role.

21. Choose Attach policy.

Create an API Gateway REST API

Create an API to serve your requests

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 Next.

6. Choose Create API.

Create resources for your API

1. In the Resources panel of your API page, select /.

2. For Actions, choose Create Resource.

3. For Resource Name, enter folder.

4. For Resource Path, enter {folder}.

5. Choose Create Resource.

6. In the Resources panel, select the /{folder} resource that you created in step 5.

7. Choose Actions, and then choose Create Resource.

8. For Resource Name, enter object.

9. For Resource Path, enter {object}.

10. Choose Create Resource.

Create a PUT method for your API for uploading image or PDF

1. Choose Actions, and then choose Create Method.

2. From the dropdown list, choose PUT, and then choose the check mark icon.

3. Under the Integration type category, choose AWS Service.

4. For AWS Region, choose us-east-1 or the AWS Region you see on the Bucket properties page.

5. For AWS Service, choose Simple Storage Service (S3).

6. Leave 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 Amazon Resource Name (ARN) for the IAM role that you created earlier. ARN creation is a part of the Create and attach an IAM policy to the API Gateway role section.

11. For Content Handling, choose Passthrough.

12. Choose Save.

Configure parameter mappings for the PUT method

1. In the Resources panel of your API page, choose PUT.

2. Choose Integration Request.

3. Expand URL Path Parameters.

4. Choose Add path.

5. For Name, enter bucket.

6. For Mapped from, enter method.request.path.folder.

7. Choose the check mark icon at the end of the row.

8. Repeat steps 4 through 7. In step 5, set Name to key. In step 6, set Mapped from to method.request.path.object.

Create a GET method for your API for retrieving an image

1. In the Resources panel of your API page, choose /{object}.

2. Choose Actions, and then choose Create Method.

3. From the dropdown list, choose GET, and then choose the check mark icon.

4. Under the Integration type category, choose AWS Service.

5. For AWS Region, choose us-east-1, or the Region you see on the Bucket properties page.

6. For AWS Service, choose Simple Storage Service (S3).

7. Leave 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 Amazon Resource Name (ARN) for the IAM role that you created earlier. ARN creation is a part of the Create and attach an IAM policy to the API Gateway role section.

12. For Content Handling, choose Passthrough.

13. Choose Save.

Configure parameter mappings for the GET method

1. In the Resources panel of your API page, choose GET.

2. Choose Integration Request.

3. Expand URL Path Parameters.

4. Choose Add path.

5. For Name, enter bucket.

6. For Mapped from, enter method.request.path.folder.

7. Choose the check mark icon at the end of the row.

8. Repeat steps 4 through 7. In step 5, set Name to key. In step 6, set Mapped from to method.request.path.object.

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

1. In the Resources panel of your API page, choose GET.

2. Choose Method Response.

3. Expand 200.

4. Under Response Body for 200, remove application/json.

5. Under Response headers for 200, choose Add header.

6. For Name, enter content-type.

7. Choose the check mark icon to save.

8. Choose Method execution to go back to the Method Execution pane.

9. Choose Integration Response.

10. Expand 200, and then expand Header Mappings.

11. Choose the pencil icon at end of the row named content-type.

12. Enter image/jpeg to see an image file.
-OR-
Enter application/pdf to see a PDF file.

Set up binary media types for the API

1. In the navigation pane of your API page, choose Settings.

2. In the Binary Media Types section, choose Add Binary Media Type.

3. In the text box, add the following string: */*

Note: Avoid putting the string in quotes. You can substitute a wildcard for a particular Multipurpose Internet Mail Extensions (MIME) type that you want to treat as a binary media type. For example, choose "image/jpeg" to have API Gateway treat JPEG images as binary media types. If you add */*, then API Gateway treats all media types as binary media types.

4. Choose Save Changes.

Resolve CORS error with binary settings for API

1. If you want to use the aforementioned APIs (PUT and GET) in a web application, you might encounter a CORS error.

2. To resolve the CORS error with binary settings turned on, start CORS from the API Gateway console.

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

4. For Actions, choose Enable CORS.

5. Choose Enable CORS and replace existing CORS headers.

6. Use the update integration CLI command to update the content handling property. By making this update, the binary content can be handled for preflight options requests with mock integration.

7. Run the two CLI commands that follow by updating the API ID, Resource ID, and AWS Region. You can obtain the API ID and Resource ID from the top of the Gateway API console when you select the {object} resource.

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>

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>

Deploy your API

1. In the navigation pane on your API page, choose Resources.

2. In the Resources pane, choose Actions, and then choose Deploy API.

3. In the Deploy API window, for Deployment 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. The invoke URL for making requests to the deployed API snapshot appears.

8. Copy the invoke URL.

Note: For more information, see Deploying a REST API in Amazon API Gateway.

Upload an image file to S3 by invoking your API

Append the bucket name and file name of the object to your API's invoke URL. Then, make a PUT HTTP request using a client of your choice. For example, with the Postman application, select PUT method from the dropdown. Select Body, then select binary. When the Select File button appears, select a local file to upload.

For more information, see Invoking a REST API in Amazon API Gateway.

Example curl command to make a PUT HTTP request to upload an image or PDF

Note: In this example abc12345 is your API ID, testfolder is your S3 bucket, and testimage.jpeg is the local file that you're uploading.

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'

Important: 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 you must add Content-Type header to your PUT request. You must set Content-Type header to image/jpeg.

Now, you can see the image or PDF in a web browser using the same URL because the web browser makes a GET request.