Object Storage APIs

Most important commands to remember

• aws s3api list-objects-v2 — list a bounded page of object keys.
• aws s3api head-object — inspect an object’s metadata without downloading its body.

Commands and flags

Command or option	Meaning
read -r -p '…' object_bucket	Prompt for a bucket name and save it without treating backslashes specially.
--bucket "$object_bucket"	Select that existing test bucket; quotes preserve the input.
--prefix lab/	Select keys beginning with these characters.
--max-keys 5 --no-paginate	Request at most five keys in one service page; do not fetch further pages.
--key lab/hello.txt	Select this exact existing object key.
--no-cli-pager	Print directly instead of opening a pager.

The configured AWS identity signs the requests. A bucket name is not a URL. These read requests can incur the service’s normal request charges.

The concepts that matter

1. The key is the object’s address

An object API addresses data through a bucket and key. The key lab/hello.txt contains a slash, but that does not make lab an ordinary filesystem directory.

Prefix listings let clients group related keys. Large listings are paginated, so a response can be correct without containing every matching object. A client that ignores continuation information can silently miss data.

2. Each API operation has its own authorization boundary

Listing a bucket and reading an object require different permissions. An identity may read a known key without being allowed to enumerate the bucket. Conversely, seeing a key does not necessarily allow downloading its contents.

Authentication identifies the caller; policies decide the requested action on the particular resource. A presigned URL delegates a bounded request under the signer’s authority and expiry rules. Possessing such a URL can be sensitive even when it contains no ordinary password.

3. Metadata is useful but does not replace the body

A HEAD request retrieves object metadata without the object data. Size, content type, modification time, and entity tags can help applications decide what to retrieve or compare.

An ETag is not universally an MD5 checksum. Multipart uploads and encryption details can change its interpretation. Use the service’s documented checksum features when you need content-integrity verification, rather than treating every ETag as the same hashing contract.

4. Consistency and concurrency are separate questions

Amazon S3 provides strong consistency for the documented object reads, writes, and listings. That does not turn several separate object updates into one transaction.

Two writers can still race to replace the same key. Conditional requests and versioning address different parts of that problem: conditions can reject an unexpected version, while versioning can preserve earlier object versions. Other S3-compatible services may have different guarantees; API resemblance does not establish identical behavior.

One small example

Optional: use your existing authorized test profile. Enter the assigned bucket name at the prompt. The example lists a small prefix and reads metadata for the stated fixture; it creates no bucket or object.

read -r -p 'Test bucket: ' object_bucket
aws s3api list-objects-v2 --bucket "$object_bucket" --prefix lab/ --max-keys 5 --no-paginate --no-cli-pager
aws s3api head-object --bucket "$object_bucket" --key lab/hello.txt --no-cli-pager

Inspect each listed Key and Size in bytes. If IsTruncated is true, more results exist beyond this deliberately limited page. In the HEAD response, compare ContentLength, ContentType, and ETag if present.

A HEAD failure does not always distinguish a missing object from insufficient permission: S3 can return different status codes depending on list permission. A successful HEAD proves metadata access, not a complete object download or concurrent-write safety. No resource cleanup is needed.

Keep this idea: Object APIs operate on keys and individual requests; directory appearance does not supply filesystem or transaction semantics.