S3 API Getting Started Guide

This guide walks through common tasks using the Filebase S3-compatible API.

What is an API?

An Application Programming Interface, or API, is a software technology that allows two applications to communicate and interact with each other.

When an application connects to the internet, it sends a request to a server for data. The server receives the request, retrieves the requested data, then sends it back to the application. When the application receives the data, it interprets it and presents it in a readable format within the application for you to read.

Another way to think about APIs is to use a real-world example. If you’re at a restaurant for dinner, you have a menu of dishes to choose from. This menu acts as your application. When the waiter takes your order, the waiter acts as the messenger, or the API, and relays your order to the kitchen. The kitchen, which acts as the data server, receives your order, prepares it, and gives it back to your waiter to bring out to you. When the waiter brings you back your food, this is the API bringing back the data request to you.

Modern APIs have universal characteristics and attributes that make them not only widely usable and transferable, but valuable to developers and end-users.

Some of these characteristics include adhering to universal standards such as HTTP and REST, making them developer-friendly and understood broadly. APIs also have a strong discipline for standardization and governance, making them scalable and performant.

Getting Started

Filebase can be used through the console web interface found at https://console.filebase.com. The getting started guide on using the web interface can be found here.

While the web interface is necessary for functions such as viewing and rotating Filebase Access Keys or updating billing information, most interactions with the Filebase platform can be executed through API requests.

This guide will cover the Filebase S3-compatible API and common tools used to interact with the Filebase API.

Signing up for Filebase

Filebase uses a web-based console that can be found at https://filebase.com/signup

Existing accounts can go directly to https://console.filebase.com.

1. To sign up for a Filebase account, navigate to https://filebase.com. To make a new account, click the ‘Try for Free’ button in the top right corner of the webpage.

2. Next, fill out the fields of the form, including an email address and password, and agree to the Filebase terms to create your account.

Note: Temporary email addresses cannot be used to create a Filebase account.

3. You will receive an email with confirmation instructions. Click the link included in the email to confirm your account and finish the registration process.

Once you’ve completed these steps, your Filebase account has been created.

Access Keys

To use the Filebase S3-compatible API, you will need to have your Filebase Access and Secret key pair to submit API requests.

To view the access key for your Filebase account, start by clicking on the ‘Access Keys’ option from the menu to open the access keys dashboard.

Here you can view the access keys for your account. Each access key has two parts, the key and the secret associated with the key. The access key dashboard will also provide information such as the time and date the access key was created and its current status.

To use access keys, you will need to have both the key and the secret associated with that key.

API endpoint

The Filebase S3-compatible API endpoint is https://s3.filebase.com.

This endpoint can be used with S3-compatible tools, SDKs, or frameworks to communicate with the Filebase platform.

Authentication

The Filebase S3-compatible API only supports AWS v4 signatures (AWS4-HMAC-SHA256) for authentication and does not support AWS v2 signatures.

HTTPS Protocol

Filebase maintains a strict HTTPS-only standard. This means objects and API calls are served only via HTTPS. The port for this connection is the HTTPS standard port 443.

It is not possible to disable this at this time. Requests sent via the HTTP protocol will be redirected to HTTPS.

Supported API Methods

The list below documents Filebase's currently supported S3 API methods.

AbortMultipartUpload

Cancels a multipart upload. Once aborted, the upload is canceled and no additional parts can be uploaded using the original upload ID. Any of the parts that were uploaded prior to the cancellation will be deleted.

CompleteMultipartUpload

Completes a previously initiated multipart upload by assembling previously uploaded parts.

CopyObject (Temporarily disabled)

Used to create a duplicate copy of an existing object. This method is currently disabled.

CreateBucket

Creates a new Filebase bucket. By default, this bucket is created on the IPFS network.

CreateMultipartUpload

Initiates a multipart upload which returns a unique upload ID value. This ID value is used to identify all parts of the multipart upload.

DeleteBucket

Removes the specified bucket from Filebase. The bucket must be empty before it can be removed.

DeleteBucketCors

Removes the current CORS policy set on the specified Filebase bucket.

DeleteObject

Removes an object from being stored on Filebase.

GetBucketAcl

Returns the specified bucket’s currently configured access control list.

GetBucketCors

Returns the specified bucket’s current CORS policy.

GetBucketLifecycle

Returns the specified bucket’s current lifecycle configuration.

GetBucketLifecycleConfiguration

Returns the specified bucket’s current lifecycle configuration.

GetBucketLocation

Returns the region of the specified bucket.

GetBucketLogging

Returns the current logging status of the specified bucket.

GetBucketVersioning

Returns the current versioning state of the specified bucket.

GetObject

Retrieves the specified object(s) from Filebase.

GetObjectAcl

Retrieves the current access control list configuration for the specified object.

HeadBucket

Used to determine if the specified bucket exists.

HeadObject

Used to determine if the specified object exists.

ListBuckets

Lists all current buckets on your Filebase account.

ListObjects

Lists all current objects within the specified bucket. Maximum return of 1,000 objects.

ListObjectsV2

Lists all current objects within the specified bucket. Maximum return of 1,000 objects. The newest version of ListObjects, and recommended for new workflows.

PutBucketAcl

Used to configure the access control list permissions on the specified bucket.

PutBucketCors

Used to configure the CORS policy on the specified bucket.

PutObject

Used to upload an object to the specified bucket.

PutObjectAcl

Used to configure the access control list permissions on the specified object.

UploadPart

Used to upload a part from a multipart upload using the upload’s unique ID value.

When a response payload is present, all responses are returned using UTF-8 encoded XML.

Pre-signed URLs

The Filebase S3-compatible API supports pre-signed URLs for downloading and uploading objects. Pre-signed URLs can be generated in a number of ways including the AWS CLI and the AWS SDKs.

For more information on Pre-signed URLS, see our guide here.

Access Control Lists (ACLs)

The Filebase S3-compatible API features limited support for Access Control Lists (ACLs). Object-level ACLs are currently not supported.

The GetObjectAcl and GetBucketAcl methods will work as expected, but the GetObjectAcl response will return the ACL of the bucket that the object is contained in.

This design eliminates the possibility of a user accidentally making an object public within a private bucket. If a mix of private and public objects is required for your workflow, you will need to create two different buckets.

Cross-Origin Resource Sharing (CORS)

Cross-origin resource sharing (CORS) creates a way for client web applications located on one domain to have the ability to interact with resources located on a different domain. With CORS, websites and applications can access files and resources stored on Filebase buckets.

The Filebase S3-compatible API supports CORS configurations for buckets.

The following API methods are supported:

  • GetBucketCors

  • PutBucketCors

  • DeleteBucketCors

To configure a Filebase bucket to allow cross-origin requests, you will need to create a CORS rule. This rule identifies the origins that you will allow to access your bucket, the HTTP methods that will be supported for each origin, and other operation-specific information.

This rule can be a JSON or XML file, though if using AWS CLI to apply this rule, a .json file is required. This example is a wildcard rule that allows cross-origin GET requests from all origins.

Example #1 JSON: This example is a wildcard rule that allows cross-origin GET requests from all origins.

{
"CORSRules":[
    {
        "AllowedHeaders": [],
        "AllowedMethods": [
            "GET"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": []
    }
    ]
}

Example #1 XML: This example is a wildcard rule that allows cross-origin GET requests from all origins.

<CORSConfiguration>
    <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
    </CORSRule>
</CORSConfiguration>

CORS also allows optional configuration parameters, as shown in the following CORS rule.

  • MaxAgeSeconds: Specifies the amount of time in seconds that the browser caches a response to a preflight OPTIONS request for the specified resource.

  • ExposeHeader: Identifies the response headers that customers are able to access from their applications. In this example, x-amz-server-side-encryption, x-amz-request-id, and x-amz-id-2.

Example #2 JSON: In this second example, the CORS rule allows cross-origin PUT, POST, and DELETE requests from the http://www.example.com origin, with a MaxAgeSeconds of 3000 and ExposeHeaders of x-amz-server-side-encryption, x-amz-request-id, and x-amz-id-2.

{
"CORSRules": [
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "PUT",
            "POST",
            "DELETE"
        ],
        "AllowedOrigins": [
            "http://www.example.com"
        ],
        "ExposeHeaders": [
            "x-amz-server-side-encryption",
            "x-amz-request-id",
            "x-amz-id-2"
        ],
        "MaxAgeSeconds": 3000
    }
    ]
}

Example #2 XML:

<CORSConfiguration>
<CORSRule>
<AllowedOrigin>http://www.example.com</AllowedOrigin>
<AllowedMethod>PUT</AllowedMethod>
<AllowedMethod>POST</AllowedMethod>
<AllowedMethod>DELETE</AllowedMethod>
<AllowedHeader>*</AllowedHeader>
<MaxAgeSeconds>3000</MaxAgeSeconds>
<ExposeHeader>x-amz-server-side-encryption</ExposeHeader>
<ExposeHeader>x-amz-request-id</ExposeHeader>
<ExposeHeader>x-amz-id-2</ExposeHeader>
</CORSRule>
</CORSConfiguration>

Applying a CORS Rule to Filebase Bucket

To apply a CORS rule, you can use a tool such as the AWS CLI to apply the .json file you created containing the rule. For information on how to configure AWS CLI, see here.

From the command line, enter the following command to apply the CORS rule to the intended Filebase bucket:

aws --endpoint https://s3.filebase.com s3api put-bucket-cors \ 
--bucket bucket-name \
--cors-configuration=file://corspolicy.json

Testing the CORS Configuration

You can confirm that the CORS configuration for the bucket was applied successfully by using the command:

aws --endpoint https://s3.filebase.com s3api get-bucket-cors \
--bucket bucket-name

Using the API

There are a wide variety of ways to interact with and use the Filebase S3-compatible API. This guide will provide a few common examples, though there are many varieties of tools, frameworks, and SDKs that are supported. For a complete list of our tool documentation, please refer to https://docs.filebase.com.

Postman

Postman is an API platform for building, developing, and using APIs.

To use Postman with Filebase, you will need a Postman account, have your Filebase access and secret keys, and have created a Filebase bucket.

First, log in to your Postman account.

Select ‘Workspaces’ from the top menu navigation bar, and select an existing workspace or create a new one.

Enter the desired settings for a new workspace if creating one.

In your workspace, select the ‘Collections’ tab on the left navigation bar, then select ‘New’.

Select ‘HTTP Request’.

Configure the settings for the HTTP Request. Select the ‘GET’ HTTP Request type, followed by the URL of your Filebase bucket.

The URL format for Filebase buckets is as follows, where ‘bucket-name’ is the name of your Filebase bucket:

https://bucket-name.s3.filebase.com

Then, select the Authorization tab. Configure the following parameters:

Type: AWS Signature

Add Authorization Data To: Request URL

Access Key: Your Filebase Access Key

Secret Key: Your Filebase Secret Key

AWS Region: us-east-1

Service Name: s3

Session Token: Not required, only necessary if using temporary credentials.

Select the blue ‘Send’ button to test your configuration. You should receive a response in XML format listing the bucket contents and metadata.

S3cmd

S3cmd is a command Line S3 Client and Backup for Linux and Mac OSx.

To use S3cmd, download the application and have your Filebase access and secret key.

To configure S3cmd, run the command:

s3cmd --configure

You will be prompted to fill out the following information:

  • Access Key: Filebase Access Key

  • Secret Key: Filebase Secret Key

  • Default Region: us-east-1

  • S3 Endpoint: s3.filebase.com

  • Bucket Name: Filebase Bucket Name

  • Encryption Password: Unique password

  • Path to GPG Program: If stored in default system location, press enter to confirm.

  • Use HTTPS Protocol: Yes

  • HTTP Proxy Server Name: Enter to bypass.

You will see a summary of these settings and be prompted to test access to Filebase with these settings. Once tested, you will be prompted to save the settings. Then you’re ready to start using S3cmd.

You can use S3cmd with commands such as the following:

  • Make bucket: s3cmd mb s3://BUCKET

  • Remove bucket: s3cmd rb s3://BUCKET

  • List objects or buckets: s3cmd ls [s3://BUCKET[/PREFIX]]

  • List all objects in all buckets: s3cmd la

  • Put file into bucket: s3cmd put FILE [FILE...] s3://BUCKET[/PREFIX]

  • Get file from bucket: s3cmd get s3://BUCKET/OBJECT LOCAL_FILE

  • Delete file from bucket: s3cmd del s3://BUCKET/OBJECT

  • Synchronize a directory tree to S3: s3cmd sync LOCAL_DIR s3://BUCKET[/PREFIX] or s3://BUCKET[/PREFIX] LOCAL_DIR

  • Disk usage by buckets: s3cmd du [s3://BUCKET[/PREFIX]]

  • Get various information about Buckets or Files: s3cmd info s3://BUCKET[/OBJECT]

  • Copy object: s3cmd cp s3://BUCKET1/OBJECT1 s3://BUCKET2[/OBJECT2]

  • Move object: s3cmd mv s3://BUCKET1/OBJECT1 s3://BUCKET2[/OBJECT2]

Cyberduck

CyberDuck is a free cloud storage browser for Windows and Mac OSX that supports Filebase, FTP, SFTP, and other cloud storage services.

To use CyberDuck with the Filebase S3-compatible API, download and install CyberDuck, have your Filebase access and secret key, and have a Filebase bucket created.

To set up CyberDuck, start by downloading the preconfigured Filebase Profile for CyberDuck.

Then open the Filebase Profile for CyberDuck. You will see the following window:

The server name and URL are preconfigured. You will need to provide your Filebase S3 API Access Key and S3 Secret Key, found in the Filebase web console under Access Keys.

After entering your credentials, close the profile window and open the CyberDuck browser. You should see your Filebase connection.

Double click on the s3.filebase.com connection to connect. You should then see a window appear that lists your existing Filebase buckets.

Double click a bucket to open the contents of the bucket.

From this window, you can click and drag files and folders from other windows to be uploaded to your Filebase bucket.

You can monitor the upload progress through the CyberDuck Transfer window.

You can confirm that the files are reflected in your Filebase bucket through the Filebase web console.

These tools are only a small sample of the full list of supported S3-compatible API tools. For a complete list of our tool documentation, please refer to https://docs.filebase.com.

If you have any questions, please join our Discord server, or send us an email at hello@filebase.com

Last updated