In order to use AWS S3 as your External Storage of choice, you must set the provider attribute to aws within the store hash and, at a minimum, provide your AWS credentials (key and secret) as well as a bucket name and the AWS region where your bucket is located. The full list of store hash attibutes for AWS S3 storage can be found below.

Alternatively, you can use our Secure Storage Connectors. Simply save your credentials in your SupaRes Account and reference themy by ID. This mechanism will greatly increase the security of your cloud credentials. When Secure Storage Connectors are in use, you only have to provide SupaRes API with your Connector id instead of provider, key, and secret properties. You can add new Connector in your SupaRes Account.

Authentication

When passing AWS credentials in your request JSON, you have to set the following authentication properties:

{
    "store": {
        "provider": "aws",
        "key": "your-aws-key",
        "secret": "your-aws-secret"
    }
}

When using Secure Storage Connectors, you only need to provide your Connector ID:

{
    "store": {
        "id": "your-connector-id"
    }
}

AWS S3 properties and settings

The SupaRes API allows you to set the following custom headers on your objects: Expires, Cache-Control, Content-Type, Content-Encoding, Content-Language and Content-Disposition.

{
    "store": {
        "provider": "aws",
        "key": "your-aws-key",
        "secret": "your-aws-secret",
        "bucket": "images",
        "region": "eu-central-1",
        "path": "assets/image.jpg",
        "acl": "public-read",
        "metadata": {
            "key": "value"
        },
        "headers": {
            "Cache-Control": "max-age=2592000000"
        },
        "tags": {
            "key": "value"
        }
    }
}

An example cURL request of using AWS S3 as External Storage provider will look like the following:

curl https://api.supares.com/1.0/fetch -X POST -u your-api-key: \
-H "Content-Type: application/json" \
-d '{
    "url": "https://www.website.com/image.jpg",
    "resize": {
        "width": 100,
        "height": 75
    },
    "store": {
        "provider": "aws",
        "key": "your-aws-key",
        "secret": "your-aws-secret",
        "bucket": "bucket-name",
        "region": "eu-central-1",
        "path": "assets/image.jpg",
        "headers": {
            "Cache-Control": "max-age=2592000000"
        }
    }
}'

When using AWS as your External Storage, the url property within the JSON response will point to the object's location within the S3 bucket and you can safely use that URL in production, for example:

HTTP/1.1 200 OK

Date: 
Status: 200 OK
Content-Type: application/json

{
    "success": true,
    "code": 200,
    "id": "9fccf4b5-cfab-4e92-9276-5d2028fcb6a0",
    "input": {
        "name": "image.jpg",
        ..
    },
    "output": {
        "url": "https://bucket-name.s3.eu-central-1.amazonaws.com/assets/image.jpg",
        ..
    }
}

Custom Bucket Policies

If you would like to create an AWS User dedicated only for the SupaRes API or are using a custom bucket policy, please make sure to include s3:PutObject and s3:PutObjectAcl entries in the allowed actions section in your bucket policy file (and replace bucket-name in this example):

{
    "Statement": {
        "Effect": "Allow",
        "Action": [
            "s3:PutObject",
            "s3:PutObjectAcl"
        ],
        "Resource": [
            "arn:aws:s3:::bucket-name/*"
        ]
    }
}