Contact Support
API Reference

Swift

📘

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 Swift protocol.

📘

Search for libraries first!

If you are developing your own application, check for an Swift-compatible library first! Some 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. Despite Swift being generally less complex than S3, it's not as common/popular so you're less likely to find a compatible library.

For convenience, here are some more common libraries available:

But be sure to check for your particular language!

Swift (also/commonly referred to as OpenStack Swift, to differentiate it from the completely unrelated Swift programming language) 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 S3) 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).

Swift is a much simpler protocol than S3, but its reference is entirely open/publicly accessible 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 Swift storage framework from other resources should work.

NetFire Cloud Storage follows the Swift specification version 1 (v1, v1.0).

Terminology

This documentation uses some shorthand terminology. Namely:

Container:

If you are used to development environment image systems like Docker, Kubernetes, etc. you may have something entirely different in mind when you hear the word "container". Likewise, if you are more experienced with S3, you may know of objects being contained in a bucket. Container(s), in Swift terminology, are directly analogous to S3 buckets -- rather than referring to a runtime system like e.g. Docker, they refer strictly to a collection of storage objects.

Container Naming Requirements and Suggestions

Because containers are more tightly bound to your tenant namespace and do not support a "DNS-style" format like S3, the naming requirements are significantly relaxed in comparison (they must be between 1-256 UTF-8 characters, and must not contain a slash (/)). However, to maintain the best possible compatibility with S3 (as your Swift containers can also be used as S3 buckets!), we recommend following the same S3 naming requirements. As such, those requirements and suggestions are reproduced here.

Container 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

Container names SHOULD:

  • Be unique globally
  • Not use periods
    • Using periods will cause S3 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/container 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.