S3 API Getting Started Guide
This guide walks through common tasks using the Filebase S3-compatible 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.
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.
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.
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.
This endpoint can be used with S3-compatible tools, SDKs, or frameworks to communicate with the Filebase platform.
The Filebase S3-compatible API only supports AWS v4 signatures (AWS4-HMAC-SHA256) for authentication and does not support AWS v2 signatures.
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.
The list below documents Filebase's currently supported S3 API methods.
When a response payload is present, all responses are returned using UTF-8 encoded XML.
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.
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) 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, andx-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>
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
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
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 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.
The URL format for Filebase buckets is as follows, where ‘bucket-name’ is the name of your Filebase bucket:
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.
S3cmd is a command Line S3 Client and Backup for Linux and Mac OSx.
To configure S3cmd, run the command:
s3cmd --configureYou will be prompted to fill out the following information:
- Access Key: Filebase Access Key
- Secret Key: Filebase Secret Key
- Default Region: us-east-1
- 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]ors3://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 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.
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.
Double click on the s3.filebase.com connection to connect. You should then see a window appear that lists your existing Filebase buckets.
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 [email protected]