Storage fundamentals
S3 API
The S3 API is the HTTP-based programming interface originally defined by Amazon for its Simple Storage Service and now implemented by most object storage systems. It specifies how applications create buckets, write, read, list and delete objects, and manage settings such as access, versioning and retention. It has become the common language between applications and object storage, in the cloud and on-premises.
What operations does the S3 API define?
The interface is a set of REST calls on two kinds of resource, buckets and objects.
| Group | Example operations | Purpose |
|---|---|---|
| Object data | PUT, GET, HEAD, DELETE object | Store, retrieve, inspect and remove objects |
| Listing | List objects, list versions | Enumerate the contents of a bucket |
| Large objects | Multipart upload, range GET | Transfer big objects in parts |
| Bucket configuration | Versioning, lifecycle, replication, logging | Set behavior for a bucket |
| Access control | Bucket policy, ACLs | Decide who may do what |
| Retention | Object Lock, legal hold | Prevent deletion for a period |
How does a request work?
Each request is an HTTPS call to an endpoint, addressed to a bucket and an object key. It is signed with the caller's access key using a scheme known as Signature Version 4, which proves who is calling and that the request has not been altered. The storage system authenticates the signature, evaluates policies, performs the operation and returns a standard HTTP status code. Software development kits for most languages wrap these details.
Why did it become a standard?
The API was never formally standardized. It became a de facto standard because a very large number of applications, backup products, analytics engines and data tools were written to it. For storage vendors, implementing the same interface meant those applications worked without modification. For users, it means the choice of storage platform can be separated from the choice of application, and data can move between platforms with ordinary tools.
What does S3 compatibility mean in practice?
No implementation outside Amazon's covers every operation, and the API keeps growing. Compatibility is a matter of degree: which operations are supported, how closely error codes and edge-case behavior match, and whether features such as Object Lock, versioning and multipart semantics behave as applications expect. The safe approach is to test the specific application against the specific platform. S3 compatible storage covers the concept, and S3-native versus S3-compatible explains why the depth of implementation matters.
Frequently asked questions
Is the S3 API only for Amazon S3?
No. Most object storage systems, cloud and on-premises, implement it.
Is the S3 API a file system interface?
No. It works on whole objects addressed by key. There are no directories or in-place edits, though keys can contain slashes that tools display as folders.
What is an S3 endpoint?
The network address an application sends S3 requests to, such as a hostname for a storage system or cloud region.
Related terms
- S3 compatible storage: systems that implement the API.
- S3 bucket: the container the API addresses.
- Object storage: the storage model behind the API.
- Multipart upload: the API's method for large objects.
- Bucket policy: access rules expressed through the API.