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

Last updated: 2021-12-09

I want to upload an image file to Amazon Simple Storage Service (Amazon S3) through Amazon API Gateway. How do I do that?

Short description

To upload a binary file (image) to an S3 bucket using API Gateway, you must activate binary support for your API Gateway REST API.

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

Resolution

Create an IAM role for API Gateway

  1. Open the IAM console.
  2. On 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 S3 later. Choose Next: Tags for now.
  8. Add tags (optional), 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. On 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 Permissions tab, choose Attach policies.
  5. Choose Create 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 select PutObject.
  9. Expand Resources, and then select Specific.
  10. Choose Add ARN.
  11. For Bucket name, enter the name of your bucket. Include the prefix, if applicable.
  12. For Object name, enter your object name.
    Note: The bucket name specifies the location of the uploaded files. The object name specifies the pattern that the object (that is, file names) must adhere to for policy alignment.
  13. Choose Add.
  14. Choose Next: Tags, add tags (optional), and then choose Next: Review.
  15. For Name, enter the name of your policy.
  16. Choose Create policy.
  17. In the policy search box, enter the name of the policy that you just created, and then select that policy.
  18. Choose Policy actions, and then choose Attach. A list of IAM roles appears.
  19. Search for the API Gateway role that you created earlier. Then, select the role.
  20. Choose Attach policy.

Create an API Gateway REST API

Create an API to serve your requests

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

Create resources for your API

  1. On 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. On the Resources panel, select the /{folder} resource that you just created.
  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

  1. On the Resources panel of your API page, choose /{object}.
  2. Choose Actions, and then choose Create Method.
  3. From the drop-down menu, choose PUT, and then choose the check mark icon.
  4. Due to a console limitation, you might see only three options. To work around this limitation, you can configure any of the available integration types temporarily and then later edit the integration request endpoint to AWS Service. For example, select HTTP Proxy for Integration type. Then, enter https://postman-echo.com/get for Endpoint URL (ignore the warning "Missing parameters:{proxy}" for now). Choose Save to save changes.
  5. Now, Select Integration Request and select AWS Service under the Integration type category.
  6. For AWS Region, choose us-west-2.
  7. For AWS Service, choose Simple Storage Service (S3).
  8. Leave AWS Subdomain empty.
  9. For HTTP method, choose PUT.
  10. For Action Type, select Use path override.
  11. For Path override (optional), enter {bucket}/{key}.
  12. For Execution role, enter the Amazon Resource Name (ARN) for the IAM role that you created earlier.
  13. For Content Handling, choose Passthrough.
  14. Choose Save.

Configure parameter mappings for the PUT method

  1. On the Resources panel of your API page, select 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 checkmark 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 Binary Media Types for the API

  1. On 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 also substitute a wildcard for a particular 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 will treat all media types as binary media types.
  4. Choose Save Changes.

Deploy your API

  1. On the navigation pane on your API page, choose Resources.
  2. On 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. On 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, the Postman application.

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

Example PUT method HTTP request

Note: This example assumes that abc is your API ID, mybucket is your S3 bucket, and myobject.jpeg is the local file that you're uploading. In this example, mybucket is substituted for {folder} and mapped to {bucket}. myobject.jpeg is substituted for {object} and mapped to {key}.

https://abc.execute-api.ap-southeast-1.amazonaws.com/v1/mybucket/myobject.jpeg

Important: If */* is included in the binary list, then you can make a PUT request to upload the file. If image.jpeg is included in the binary list, then you must add Content-Type header to your PUT request. You must set Content-Type header to image/jpeg.


Did this article help?


Do you need billing or technical support?