Contact Support
API Reference

S3

📘

This documentation is primarily for developers!

The docs here are highly technical and are generally only useful if you're writing software. If you're more interested in just getting access to your NetFire Cloud Storage so you can upload/download files, you may want a client program that already supports the S3 protocol.

📘

Search for libraries first!

If you are developing your own application, check for an S3-compatible library first! Most languages already have libraries available. The documentation provided here is largely for implementing interactions yourself if your language lacks a library and only documents the most basic operations.

For convenience, here are some more common libraries available:

But be sure to check for your particular language! There almost assuredly is a library for it already.

S3 is a set of data formats, features, and specifications that define one type of cloud storage access. It (along with other cloud storage specifications such as Swift) can be thought of as "sub-protocols" of HTTP (which itself is a "sub-protocol" of TCP, or UDP in the case of HTTP/3).

S3 is a very large framework, so only the most common operations are provided in our documentation. However, feel free to reach out to us if you need assistance, and most documentation available for the S3 framework from other resources should work.

Terminology

This documentation uses some shorthand terminology. Namely:

DNS buckets:
This is the modern preferred way of referencing buckets and is the expected format for most modern S3 clients and libraries. They take the form of https://<bucket name>.<zone>.s3.netfire.com or, if you're a tenanted service with NetFire and have contacted us to configure a custom endpoint domain, you can and should use https://<bucket_name>.<your custom storage domain>/.

Path buckets:
This is a legacy format of bucket referencing. Many S3 clients no longer support this format. In this format, the URL base is formed via https://<zone>.s3.netfire.com/<tenant name>:<bucket name>/ or, if you're a tenanted service with NetFire with a dedicated endpoint, it would be https://<your custom storage domain>/<bucket name>.

📘

The documentation favors DNS buckets.

All example requests, responses, etc. will be provided for DNS bucketing only. However, if you require use of path bucketing, just remember that the key difference is the URL base -- for DNS buckets, it's /, for path buckets it's /<tenant>:<bucket>/.

🚧

DNS Buckets may be unpredictable for public links!

If you happen to have the same bucket name as another tenant and wish to use public links, behavior is not guaranteed. You must either use presigned URLs or use path-based bucketing when sharing public links to objects!

DNS buckets are supported for authenticated requests inherently as the tenant is identifiable based on the authentication itself.

Bucket Naming Requirements and Suggestions

Bucket names MUST:

  • Be between 3-63 characters long
  • Be unique within your tenant
  • Be lowercase
  • Start and end with a (lowercase) letter or number
  • Only consist of (lowercase) letters, numbers, hyphens, and periods

Bucket names SHOULD:

  • Be unique globally
  • Not use periods
    • Using periods will cause DNS bucketing to not be possible without extensive additional setup, which may incur an additional premium cost. If you do not wish to be susceptible to these possible extra setup costs but still use periods in your bucket names, you must use path bucketing.
  • Use UUID4 names (see RFC 4122 § 4.4) if possible (e.g. 83f41f50-6c76-4794-97f5-8f3e5419f4c7)
    • While certainly not a requirement and not very descriptive, it is guaranteed to be unique. This is highly recommended for programmatic usage and satisfies all above requirements and suggestions.
    • Alternatively, a randomly-generated 31-byte sequence in lowercase canonical hex (e.g. zero-padded 2-byte pairs, for example 97ae8b22c1131fd38a0f56c618622b1306c74c374f2394807d4d775aa427ce) will also satisfy all above requirements and suggestions and is easily generated in code. It does not need to be "near-true random"/"cryptographically-safe" random, but can be if you so desire.