Using the S3 API
The S3 API is a set of web requests — the one Amazon S3 uses — to upload, download and list files. IBEE Object Storage speaks the common parts of it, so most S3 tools and libraries work after you change three settings: the endpoint, the region and the addressing style. This page lists those settings, shows working examples, says which S3 calls IBEE serves and which it doesn’t, and explains the errors you may see.
When to use the S3 API
IBEE Object Storage has two APIs. They split the work the same way the portal does.
How it works
- Your tool signs each request with your Secret Access Key, using AWS Signature Version 4 (SigV4). The signature includes the region, which must be
auto. - The request goes to your workspace’s endpoint, with the bucket name in the path:
https://WORKSPACE-ID.blob.ibeestorage.com/my-bucket/photo.jpg. - IBEE checks the signature, the clock (within 15 minutes) and the credential’s permission level, then runs the operation or returns an XML error.
Before you begin
- An S3 credential — Access Key ID and Secret Access Key — for the bucket’s workspace, with a permission level that allows what you want to do (for example Object Read & Write to upload). See API Credentials.
- Your S3 Endpoint, shown when you create the credential:
https://WORKSPACE-ID.blob.ibeestorage.com. - A bucket. Create buckets in the portal, so you can choose the location. The REST API can do this too once its management resumes. See Buckets.
- A current version of your tool. Recent AWS CLI v2 and SDK versions add an upload checksum automatically, which IBEE needs for some uploads (see Troubleshooting).
The three settings every tool needs
Connect your tool
SDKs
Set the same three values when you create the client. These examples upload a file and list the bucket.
With rclone, test the remote with rclone lsd ibee:, which lists your buckets.
Verify
Run aws s3 ls s3://my-bucket/ --endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com --profile ibee. A list of keys (or an empty result for an empty bucket) means the endpoint, region, path style and credential are all right. Any error comes back as XML with a Code and a Message; look it up in Troubleshooting.
S3 operations IBEE serves
A “folder” is just a key prefix; Create Folder in the portal makes an empty object whose key ends in /.
S3 calls that return 501 Not Implemented
Other S3 calls — bucket configuration, tagging, ACLs and per-object retention among them — return 501 with the code NotImplemented and the message The requested S3 operation or query combination is not supported. Use the portal instead, or the REST API once its management resumes:
Limits and timing
Troubleshooting
Related pages
- API Credentials: create, scope and revoke S3 credentials
- Presigned URLs: links that work without keys
- Buckets: create buckets and use the REST API
- Limits
- Mount a Bucket as a Filesystem
