Contact Support
API Reference

Introduction to Cloud Storage API

📘

Most of this documentation is primarily for developers!

The protocol-specific documentation for this API is highly technical and is 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 a Cloud Storage protocol. You can find a convenient list of tested and supported GUI/CLI clients here.

If this is your first time using object/cloud storage, however, this page (and the FAQ) will provide you with some information you may find helpful.

Increasingly often, it is required to store data somewhere in a manner which allows either public access to that data or to collaboratively share that data with teammates.

Cloud storage, a type of object storage, was designed specifically for that purpose. Continue below for a brief introduction of what object storage, specifically cloud storage, is and how it differs from more traditional storage.

Block Storage vs. Object/Cloud Storage

Block Storage

Traditionally, shared data access was achieved with "fileservers" which typically offered FTP access, or were mounted to computers via NFS or Windows Shares. These are examples of block storage, in which the data would be represented by a filesystem.

Examples of block storage are the hard drives or SSD/NVMe disks in your computer, USB drives, RAID, iSCSI, and optical media such as DVD-ROMs.

Object/Cloud Storage

Object storage, as opposed to block storage, instead presents data as a more amorphous collection of pieces of data ("objects") with metadata tied to those objects. Often it is an abstraction on top of an "invisible" traditional filesystem (block storage) that adds functionality not natively supported by the underlying filesystem. Most modern mobile phones, for instance, present their storage as a block storage type of interface rather than a traditional filesystem (despite actually using a traditional filesystem at a lower level).

Cloud storage implements object storage and presents access via HTTP(S). It typically adds scalability, geographical mirroring for optimized delivery, failure resiliency, publishing features, and more.

Organization

In a filesystem, files are usually organized in a hierarchical manner via directories (sometimes referred to as folders) and subdirectories. e.g.:

parent/
├── dir1/
│   ├── "A.txt"
│   ├── subdir1/
│   │   └── "B.txt"
│   └── subdir2/
│       ├── "C.txt"
│       └── subdir2.1/
│           └── "D.txt"
└── dir2/
    └── "E.txt"

In object storage, however, files (objects) are typically organized together in a collection (a bucket in S3, a container in Swift) and are then typically organized by their metadata itself - tagging/labeling, and so forth. While directory paths can be emulated via object name prefixes and some clients or libraries may abstract them as directories/subdirectories, object storage tends to be much more "flat" -- directories/subdirectories don't truly/actually exist in the actual storage mechanism. This is why you cannot create or delete directories or subdirectories in Cloud Storage - they don't actually exist! e.g.:

bucketname_or_container_name:
├── "dir1/A.txt"
├── "dir1/subdir1/B.txt"
├── "dir1/subdir2/C.txt"
├── "dir1/subdir2/subdir2.1/D.txt"
└── "dir2/E.txt"

Locations

NetFire Cloud Storage offers multiple locations for storing and serving your data. They are separated into realms, regions, and zones.

📘

Documentation examples use us-east1 zone!

All requests in the examples provided throughout this documentation that use explicit URLs use the us-east1 zone, so adjust your usage appropriately.

Realms

Realms span large mostly-continuous spanses of similar geopolitical area -- they aren't quite continents, but close to it.

They contain regions.

Buckets are able to be duplicated across multiples zones within the same realm upon request. Buckets may be able to be duplicated across realms in the future upon request.

Current realms available are:

  • us
  • eu

Regions

Regions cover mostly-contiguous areas of land that typically share common network peering over the Internet. For example, for countries with coastlines the entire coast would be a region.

They contain zones.

Each region's name starts with the realm it is located in.

Buckets are able to be duplicated across multiple zones within the same region or from one region to another upon request.

Current regions available are:

  • us-east
  • eu-central

Zones

Zones are assigned based on very low-latency connections. Servers in a zone have native redundancy/failover features with other servers in the same zone.

Each zone's name starts with the region it is located in and is assigned a numerical identifier.

Buckets are able to be duplicated across multiple zones within the same region upon request.

Current zones available are:

  • us-east1
  • us-east2
  • eu-central1

Protocols

Object storage "protocols" ("specifications and interfaces" would be more accurate) 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).

NetFire Cloud Storage currently offers the following standard protocols:

S3

S3 endpoints are as follows, depending on zone:

More information on our S3 offering can be found in the S3 section.

Swift

The Swift endpoints are as follows, depending on zone:

More information on our S3 offering can be found in the Swift section.