S3-compatible API

Gigadrive Network buckets answer the S3 API, so anything that already speaks S3 works after an endpoint override. Use it for bulk copies and migrations, and for integrations that know no other way to move a file.

Connection settings

The region is a formality: any region string authenticates, and us-east-1 is what the console shows. Send that one and clients that insist on a region will stop complaining.

Connecting a client

Each snippet lists the objects in one bucket and uploads a file.

export AWS_ACCESS_KEY_ID=GAK7QM4ZTB2XVC5HJ3RN
export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_ACCESS_KEY
export AWS_DEFAULT_REGION=us-east-1

aws --endpoint-url https://api.gigadrive.network/s3 \
  s3 ls s3://user-uploads-k7qm4ztb

aws --endpoint-url https://api.gigadrive.network/s3 \
  s3 cp ./avatar.png s3://user-uploads-k7qm4ztb/avatars/user-123.png

Virtual-host addressing, where the bucket becomes a subdomain of the endpoint, is not served at all. Path style is the setting to check first when a client cannot see a bucket you know exists.

Authentication

Signature Version 4, in the Authorization header or as presigned query parameters, both with aws-chunked payloads. The service name has to be s3; the region in the credential scope is accepted whatever it says. Requests signed more than 15 minutes away from the server clock are rejected with RequestTimeTooSkewed.

Credentials are read from the database on every request, so revoking one takes effect on the next call rather than after a cache expires. A credential belongs to one application environment: addressing a bucket in a different environment returns AccessDenied.

Supported operations

ListObjectsV2 supports prefix, delimiter, max-keys, continuation-token, start-after and marker. CopyObject is served without moving bytes: the copy points at the same stored content. An HTTP method the endpoint does not handle answers MethodNotAllowed, and UploadPartCopy answers NotImplemented.

Differences from Amazon S3

CreateBucket takes the name you send as both the bucket name and its globally unique slug. A name somebody else already holds answers BucketAlreadyExists; one of your own answers BucketAlreadyOwnedByYou. Creating buckets from the console, the API or gigadrive.yaml avoids the collision, because Network generates the slug for you. x-amz-acl: public-read on CreateBucket makes the new bucket public.

DeleteObject and DeleteObjects are soft deletes. The object moves to the bucket trash, stays restorable, and keeps counting toward stored bytes until it is purged. A tool that expects DeleteObject to reclaim space will not see that happen here.

Object versioning does not exist. GetBucketVersioning answers an empty configuration, and writing to a key that already holds an object replaces it.

Errors

Failures come back as the standard S3 XML <Error> document. The codes you are most likely to hit: