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

Last updated: 2021-06-01

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

Short description

To upload a binary file (image) to an S3 bucket using API Gateway, you must enable binary support for your API Gateway API. To allow your API to access your S3 bucket, you must create an AWS Identity and Access Management (IAM) role. The IAM role must have permissions for API Gateway to perform Put operations 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.
  19. On the navigation pane, choose Roles.
  20. Search for and then select the API Gateway role that you created earlier.
  21. Choose Policy actions, and then choose Attach.
    Note: The policy permissions allow API Gateway to upload objects to your bucket with the PutObject API call.

Create an API Gateway 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. For Integration type, select AWS Service.
  5. For AWS Region, choose us-west-2.
  6. For AWS Service, choose Simple Storage Service (S3).
  7. Leave AWS Subdomain empty.
  8. For HTTP method, choose PUT.
  9. For Action Type, select 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.
  12. For Content Handling, choose Passthrough.
  13. Choose Save.

Create a PUT method for your API

  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.

You now see the invoke URL for making requests to the deployed API snapshot.

Copy the invoke URL and append the bucket name and filename of the object to make a PUT HTTP request using a client. You can use a client of your choice. For example, you can use Postman.

Consider the following example HTTP request. The 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}, while myobject.jpeg is substituted for {object} and mapped to {key}.

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

Note: 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?