The S3 API
SwiftFS implements the Amazon S3 REST API. Anything that can talk to S3 with a custom endpoint can talk to SwiftFS: point it at the endpoint, give it an access key, and keep your code.
SwiftFS has two APIs, and they are separate:
| S3 API | Management API | |
|---|---|---|
| What for | Buckets and objects: the data | Accounts, organizations, members, keys, usage, billing (SwiftFS Cloud) |
| Speaks | AWS's S3 protocol (XML) | JSON over HTTPS |
| Signed with | Access keys (SigV4) | A signed-in session |
| Documented in | These pages and the compatibility matrix | Management API |
Endpoint and region
For SwiftFS Cloud the endpoint is https://s3.swiftfs.rw and the region is
us-east-1. A self-hosted deployment has its own (SWIFTFS_PUBLIC_ENDPOINT
and SWIFTFS_REGION). Clients must sign for the configured region.
Addressing
- Path style (
https://endpoint/bucket/key) works everywhere. Most SDKs need it switched on:forcePathStyle: truein JavaScript,UsePathStyle = truein Go (see SDKs and tools). - Virtual-hosted style (
https://bucket.endpoint/key) works where the operator has set up wildcard DNS and TLS (SWIFTFS_S3_DOMAINwhen self-hosting).
Signing
Requests are signed with AWS Signature Version 4, either in the
Authorization header or in the query string of a
presigned URL. All the payload modes
the AWS SDKs use are accepted: signed and unsigned payloads, and streamed
uploads with chunk signatures or trailing checksums. Signature Version 2 is
not supported. The clock may be off by up to 15 minutes.
Limits
| Limit | Value |
|---|---|
| Object size, one request (PutObject, CopyObject) | 5 GiB |
| Object size, multipart | 10,000 parts of up to 5 GiB each |
| Smallest part (all but the last) | 5 MiB |
User metadata (x-amz-meta-*) | 2 KB |
| Keys per DeleteObjects request | 1,000 |
| Keys per listing page | 1,000 |
| Presigned URL lifetime | 7 days |
| Bucket name | 3–63 characters, unique across SwiftFS |
Errors
Errors use S3's XML format, codes and HTTP statuses, so SDKs handle them as they would with AWS. Two come from SwiftFS's own protections:
| Response | Meaning | What to do |
|---|---|---|
503 SlowDown | A rate limit was reached | SDKs retry with backoff by themselves |
403 QuotaExceeded | The account reached a storage, bucket or object quota | Delete data, or ask for a higher quota |
Requests for features SwiftFS doesn't implement fail with
501 NotImplemented, never silently. Every response carries a request ID
(x-amz-request-id, also X-SwiftFS-Request-ID); quote it when asking for
help.
What isn't supported yet
Bucket versioning, lifecycle rules, server-side encryption, object tagging operations, Object Lock, browser form uploads (POST Object) and Signature Version 2. The compatibility matrix has the complete, tested list.