Just like container operations, certain operations can be performed on/with objects as well.

All requests mentioned here require authentication.

Object URLs

Aside from list operations, all operations operate on the object URL, which follows the format of the Container URL and object name (i.e. <X-Storage-Url>/<container name>/<object name>).

List Objects

Object listing can be performed via a GET request against your Storage URL (X-Storage-Url) and container (i.e. <X-Storage-Url>/<container>).

In addition to all of the URL query parameters supported by container listing requests (and including the same pagination behavior and recommendations), it supports several extra URL query parameters.

The delimiter URL query parameter allows you to specify a separator between the object name's prefix and the remainder of the object name. See the JSON example and XML example so you can see how drastically this affects the response body. If delimiter is specified, the path URL query parameter and/or allow_unordered URL query parameter must not be specified.

The prefix URL query parameter will limit returned objects to a common object name prefix. e.g. if you have five objects cat.png, dog.png, caterpillar.png, catchemall/pokemanz.jpg, and crow.jpg in a container and specify prefix=cat, then cat.png, caterpillar.png, and catchemall/pokemanz.jpg will be listed but not dog.png or crow.png. If prefix is specified, the path URL query parameter must not be specified.

The path URL query parameter is a little like the prefix URL query parameter above, except it treats the provided value as a virtual "hierarchy path" and will only list direct objects in that "path" (which is actually a name prefix). "Child paths" will not be listed. Confused yet? The JSON example and XML example should clarify this. Note: a trailing slash (/) should make no difference in behavior. If path is specified, the delimiter URL query parameter and/or prefix URL query parameter and/or allow_unordered URL query parameter must not be specified.

The allow_unordered URL query parameter provides container listing optimization. If you don't need the container names sorted (or "ordered"), you can receive a return slightly faster by specifying allow_unordered=true. If allow_unordered is specified/true, the delimiter URL query parameter and/or path URL query parameter must not be specified.

Prefixes, Not Paths

At first glance this may seem that there actually are directories in object storage! But no; as you'll recall, this is actually an object "prefix" -- merely a text string. This allows for some clever tricks if you have public objects as it can ease transition from more traditional filesystem-backed webservers that may have files in certain directories.

📘
Transitioning to NetFire Cloud Storage can be painless!
If a prefix is used to match the same path of a file/files in your current web application, a transition from your webserver to NetFire Cloud Storage as a CDN can be seamless. Get in touch and our staff will help you make the jump!

For clarification, prefixes are more like a filename than an actual directory path/folder path. An object is "named" foo/bar/baz.tzt, it isn't a file named baz.txt in a subdirectory of foo/ called bar/.

JSON

# BEGIN REQUEST #
GET /v1/AUTH_NetFire$example/example?format=json HTTP/1.1
Host: us-east1.swift.netfire.com
X-Auth-Token: [REDACTED]
User-Agent: python-swiftclient-4.3.0
# END REQUEST #

# BEGIN REQUEST #
HTTP/1.1 200 OK
Content-Length: 1068
X-Timestamp: 0.00000
X-Container-Object-Count: 7
X-Container-Bytes-Used: 1048347
X-Container-Bytes-Used-Actual: 1064960
X-Storage-Policy: default-placement
X-Storage-Class: STANDARD
Last-Modified: Sat, 30 Sep 2023 08:24:23 GMT
X-Trans-Id: tx00000372c820bb96a775c-00651838b6-988dcc-us-east1
X-Openstack-Request-Id: tx00000372c820bb96a775c-00651838b6-988dcc-us-east1
Accept-Ranges: bytes
Content-Type: application/json; charset=utf-8
Date: Sat, 30 Sep 2023 15:03:18 GMT
Connection: close

## BEGIN REQUEST BODY ##
[{"name":"cat.png","hash":"8783c70360231686325c4952c87e5bc4","bytes":24351,"content_type":"image/png","last_modified":"2023-09-14T00:11:28.792Z"},{"name":"example.txt","hash":"ce90a5f32052ebbcd3b20b315556e154","bytes":46,"content_type":"text/plain","last_modified":"2023-03-06T17:34:12.650Z"},{"name":"exampleprefix1/exampleprefix2/main.py","hash":"fe08890fb28a0fa6fd48b988a46c5f9c","bytes":9313,"content_type":"text/x-script.python","last_modified":"2023-03-08T22:09:20.737Z"},{"name":"meme.png","hash":"eb1c50662e6a9f64f55386584e483bc5","bytes":990237,"content_type":"image/png","last_modified":"2023-09-13T23:52:48.529Z"},{"name":"pathprefix1/cat.png","hash":"8783c70360231686325c4952c87e5bc4","bytes":24351,"content_type":"image/png","last_modified":"2023-09-30T08:24:23.754Z"},{"name":"testfile","hash":"18f2ae724cf04ac1b5306f8cf9a6137d","bytes":32,"content_type":"text/plain","last_modified":"2023-03-13T11:04:49.657Z"},{"name":"upfile","hash":"909ef0d762160c163d5bf71adca22ea8","bytes":17,"content_type":"text/plain","last_modified":"2023-03-07T05:38:16.622Z"}]
## END REQUEST BODY ##
# END REQUEST #

"Prettified" response body:

[
  {
    "name": "cat.png",
    "hash": "8783c70360231686325c4952c87e5bc4",
    "bytes": 24351,
    "content_type": "image/png",
    "last_modified": "2023-09-14T00:11:28.792Z"
  },
  {
    "name": "example.txt",
    "hash": "ce90a5f32052ebbcd3b20b315556e154",
    "bytes": 46,
    "content_type": "text/plain",
    "last_modified": "2023-03-06T17:34:12.650Z"
  },
  {
    "name": "exampleprefix1/exampleprefix2/main.py",
    "hash": "fe08890fb28a0fa6fd48b988a46c5f9c",
    "bytes": 9313,
    "content_type": "text/x-script.python",
    "last_modified": "2023-03-08T22:09:20.737Z"
  },
  {
    "name": "meme.png",
    "hash": "eb1c50662e6a9f64f55386584e483bc5",
    "bytes": 990237,
    "content_type": "image/png",
    "last_modified": "2023-09-13T23:52:48.529Z"
  },
  {
    "name": "pathprefix1/cat.png",
    "hash": "8783c70360231686325c4952c87e5bc4",
    "bytes": 24351,
    "content_type": "image/png",
    "last_modified": "2023-09-30T08:24:23.754Z"
  },
  {
    "name": "testfile",
    "hash": "18f2ae724cf04ac1b5306f8cf9a6137d",
    "bytes": 32,
    "content_type": "text/plain",
    "last_modified": "2023-03-13T11:04:49.657Z"
  },
  {
    "name": "upfile",
    "hash": "909ef0d762160c163d5bf71adca22ea8",
    "bytes": 17,
    "content_type": "text/plain",
    "last_modified": "2023-03-07T05:38:16.622Z"
  }
]

`delimiter` == `/`

# BEGIN REQUEST #
GET /v1/AUTH_NetFire$example/example?format=json&delimiter=/ HTTP/1.1
Host: us-east1.swift.netfire.com
X-Auth-Token: [REDACTED]
User-Agent: python-swiftclient-4.3.0
# END REQUEST #

# BEGIN RESPONSE #
HTTP/1.1 200 OK
Content-Length: 781
X-Timestamp: 0.00000
X-Container-Object-Count: 7
X-Container-Bytes-Used: 1048347
X-Container-Bytes-Used-Actual: 1064960
X-Storage-Policy: default-placement
X-Storage-Class: STANDARD
Last-Modified: Sat, 30 Sep 2023 08:24:23 GMT
X-Trans-Id: tx000009320a74b3d0e60c8-0065183948-988dc3-us-east1
X-Openstack-Request-Id: tx000009320a74b3d0e60c8-0065183948-988dc3-us-east1
Accept-Ranges: bytes
Content-Type: application/json; charset=utf-8
Date: Sat, 30 Sep 2023 15:05:44 GMT
Connection: close

## BEGIN RESPONSE BODY ##
[{"name":"cat.png","hash":"8783c70360231686325c4952c87e5bc4","bytes":24351,"content_type":"image/png","last_modified":"2023-09-14T00:11:28.792Z"},{"name":"example.txt","hash":"ce90a5f32052ebbcd3b20b315556e154","bytes":46,"content_type":"text/plain","last_modified":"2023-03-06T17:34:12.650Z"},{"subdir":"exampleprefix1/"},{"name":"meme.png","hash":"eb1c50662e6a9f64f55386584e483bc5","bytes":990237,"content_type":"image/png","last_modified":"2023-09-13T23:52:48.529Z"},{"subdir":"pathprefix1/"},{"name":"testfile","hash":"18f2ae724cf04ac1b5306f8cf9a6137d","bytes":32,"content_type":"text/plain","last_modified":"2023-03-13T11:04:49.657Z"},{"name":"upfile","hash":"909ef0d762160c163d5bf71adca22ea8","bytes":17,"content_type":"text/plain","last_modified":"2023-03-07T05:38:16.622Z"}]
## END RESPONSE BODY ##
# END RESPONSE #

"Prettified" response body:

[
  {
    "name": "cat.png",
    "hash": "8783c70360231686325c4952c87e5bc4",
    "bytes": 24351,
    "content_type": "image/png",
    "last_modified": "2023-09-14T00:11:28.792Z"
  },
  {
    "name": "example.txt",
    "hash": "ce90a5f32052ebbcd3b20b315556e154",
    "bytes": 46,
    "content_type": "text/plain",
    "last_modified": "2023-03-06T17:34:12.650Z"
  },
  {
    "subdir": "exampleprefix1/"
  },
  {
    "name": "meme.png",
    "hash": "eb1c50662e6a9f64f55386584e483bc5",
    "bytes": 990237,
    "content_type": "image/png",
    "last_modified": "2023-09-13T23:52:48.529Z"
  },
  {
    "subdir": "pathprefix1/"
  },
  {
    "name": "testfile",
    "hash": "18f2ae724cf04ac1b5306f8cf9a6137d",
    "bytes": 32,
    "content_type": "text/plain",
    "last_modified": "2023-03-13T11:04:49.657Z"
  },
  {
    "name": "upfile",
    "hash": "909ef0d762160c163d5bf71adca22ea8",
    "bytes": 17,
    "content_type": "text/plain",
    "last_modified": "2023-03-07T05:38:16.622Z"
  }
]

`path` == `exampleprefix1/`

# BEGIN REQUEST #
GET /v1/AUTH_NetFire$example/example?format=json&path=exampleprefix1 HTTP/1.1
Host: us-east1.swift.netfire.com
X-Auth-Token: [REDACTED]
User-Agent: python-swiftclient-4.3.0
# END REQUEST #

# BEGIN RESPONSE #
HTTP/1.1 200 OK
Content-Length: 45
X-Timestamp: 0.00000
X-Container-Object-Count: 7
X-Container-Bytes-Used: 1048347
X-Container-Bytes-Used-Actual: 1064960
X-Storage-Policy: default-placement
X-Storage-Class: STANDARD
Last-Modified: Sat, 30 Sep 2023 08:24:23 GMT
X-Trans-Id: tx00000c5431c425cdf4be7-006518398a-988dd5-us-east1
X-Openstack-Request-Id: tx00000c5431c425cdf4be7-006518398a-988dd5-us-east1
Accept-Ranges: bytes
Content-Type: application/json; charset=utf-8
Date: Sat, 30 Sep 2023 15:06:50 GMT
Connection: close

## BEGIN RESPONSE BODY ##
[{"subdir":"exampleprefix1/exampleprefix2/"}]
## END RESPONSE BODY ##
# END RESPONSE #

"Prettified" response body:

[
  {
    "subdir": "exampleprefix1/exampleprefix2/"
  }
]

XML

# BEGIN REQUEST #
GET /v1/AUTH_NetFire$example/example?format=xml HTTP/1.1
Host: us-east1.swift.netfire.com
X-Auth-Token: [REDACTED]
User-Agent: python-swiftclient-4.3.0
# END REQUEST #

# BEGIN RESPONSE #
HTTP/1.1 200 OK
Content-Length: 1493
X-Timestamp: 0.00000
X-Container-Object-Count: 7
X-Container-Bytes-Used: 1048347
X-Container-Bytes-Used-Actual: 1064960
X-Storage-Policy: default-placement
X-Storage-Class: STANDARD
Last-Modified: Sat, 30 Sep 2023 08:24:23 GMT
X-Trans-Id: tx0000007861a2fcc2a2998-00651838b6-988dd5-us-east1
X-Openstack-Request-Id: tx0000007861a2fcc2a2998-00651838b6-988dd5-us-east1
Accept-Ranges: bytes
Content-Type: application/xml; charset=utf-8
Date: Sat, 30 Sep 2023 15:03:18 GMT
Connection: close

## BEGIN RESPONSE BODY ##
<?xml version="1.0" encoding="UTF-8"?><container name="example"><object><name>cat.png</name><hash>8783c70360231686325c4952c87e5bc4</hash><bytes>24351</bytes><content_type>image/png</content_type><last_modified>2023-09-14T00:11:28.792Z</last_modified></object><object><name>example.txt</name><hash>ce90a5f32052ebbcd3b20b315556e154</hash><bytes>46</bytes><content_type>text/plain</content_type><last_modified>2023-03-06T17:34:12.650Z</last_modified></object><object><name>exampleprefix1/exampleprefix2/main.py</name><hash>fe08890fb28a0fa6fd48b988a46c5f9c</hash><bytes>9313</bytes><content_type>text/x-script.python</content_type><last_modified>2023-03-08T22:09:20.737Z</last_modified></object><object><name>meme.png</name><hash>eb1c50662e6a9f64f55386584e483bc5</hash><bytes>990237</bytes><content_type>image/png</content_type><last_modified>2023-09-13T23:52:48.529Z</last_modified></object><object><name>pathprefix1/cat.png</name><hash>8783c70360231686325c4952c87e5bc4</hash><bytes>24351</bytes><content_type>image/png</content_type><last_modified>2023-09-30T08:24:23.754Z</last_modified></object><object><name>testfile</name><hash>18f2ae724cf04ac1b5306f8cf9a6137d</hash><bytes>32</bytes><content_type>text/plain</content_type><last_modified>2023-03-13T11:04:49.657Z</last_modified></object><object><name>upfile</name><hash>909ef0d762160c163d5bf71adca22ea8</hash><bytes>17</bytes><content_type>text/plain</content_type><last_modified>2023-03-07T05:38:16.622Z</last_modified></object></container>
## END RESPONSE BODY ##
# END RESPONSE #

"Prettified" response body:

<?xml version="1.0" encoding="UTF-8"?>
<container name="example">
  <object>
    <name>cat.png</name>
    <hash>8783c70360231686325c4952c87e5bc4</hash>
    <bytes>24351</bytes>
    <content_type>image/png</content_type>
    <last_modified>2023-09-14T00:11:28.792Z</last_modified>
  </object>
  <object>
    <name>example.txt</name>
    <hash>ce90a5f32052ebbcd3b20b315556e154</hash>
    <bytes>46</bytes>
    <content_type>text/plain</content_type>
    <last_modified>2023-03-06T17:34:12.650Z</last_modified>
  </object>
  <object>
    <name>exampleprefix1/exampleprefix2/main.py</name>
    <hash>fe08890fb28a0fa6fd48b988a46c5f9c</hash>
    <bytes>9313</bytes>
    <content_type>text/x-script.python</content_type>
    <last_modified>2023-03-08T22:09:20.737Z</last_modified>
  </object>
  <object>
    <name>meme.png</name>
    <hash>eb1c50662e6a9f64f55386584e483bc5</hash>
    <bytes>990237</bytes>
    <content_type>image/png</content_type>
    <last_modified>2023-09-13T23:52:48.529Z</last_modified>
  </object>
  <object>
    <name>pathprefix1/cat.png</name>
    <hash>8783c70360231686325c4952c87e5bc4</hash>
    <bytes>24351</bytes>
    <content_type>image/png</content_type>
    <last_modified>2023-09-30T08:24:23.754Z</last_modified>
  </object>
  <object>
    <name>testfile</name>
    <hash>18f2ae724cf04ac1b5306f8cf9a6137d</hash>
    <bytes>32</bytes>
    <content_type>text/plain</content_type>
    <last_modified>2023-03-13T11:04:49.657Z</last_modified>
  </object>
  <object>
    <name>upfile</name>
    <hash>909ef0d762160c163d5bf71adca22ea8</hash>
    <bytes>17</bytes>
    <content_type>text/plain</content_type>
    <last_modified>2023-03-07T05:38:16.622Z</last_modified>
  </object>
</container>

`delimiter` == `/`

# BEGIN REQUEST #
GET /v1/AUTH_NetFire$example/example?format=xml&delimiter=/ HTTP/1.1
Host: us-east1.swift.netfire.com
X-Auth-Token: [REDACTED]
User-Agent: python-swiftclient-4.3.0
# END REQUEST #

# BEGIN RESPONSE #
HTTP/1.1 200 OK
Content-Length: 1181
X-Timestamp: 0.00000
X-Container-Object-Count: 7
X-Container-Bytes-Used: 1048347
X-Container-Bytes-Used-Actual: 1064960
X-Storage-Policy: default-placement
X-Storage-Class: STANDARD
Last-Modified: Sat, 30 Sep 2023 08:24:23 GMT
X-Trans-Id: tx00000cf80d6cfe92ded75-0065183948-988dcc-us-east1
X-Openstack-Request-Id: tx00000cf80d6cfe92ded75-0065183948-988dcc-us-east1
Accept-Ranges: bytes
Content-Type: application/xml; charset=utf-8
Date: Sat, 30 Sep 2023 15:05:44 GMT
Connection: close

## BEGIN RESPONSE BODY ##
<?xml version="1.0" encoding="UTF-8"?><container name="example"><object><name>cat.png</name><hash>8783c70360231686325c4952c87e5bc4</hash><bytes>24351</bytes><content_type>image/png</content_type><last_modified>2023-09-14T00:11:28.792Z</last_modified></object><object><name>example.txt</name><hash>ce90a5f32052ebbcd3b20b315556e154</hash><bytes>46</bytes><content_type>text/plain</content_type><last_modified>2023-03-06T17:34:12.650Z</last_modified></object><subdir name="exampleprefix1/"><name>exampleprefix1/</name></subdir><object><name>meme.png</name><hash>eb1c50662e6a9f64f55386584e483bc5</hash><bytes>990237</bytes><content_type>image/png</content_type><last_modified>2023-09-13T23:52:48.529Z</last_modified></object><subdir name="pathprefix1/"><name>pathprefix1/</name></subdir><object><name>testfile</name><hash>18f2ae724cf04ac1b5306f8cf9a6137d</hash><bytes>32</bytes><content_type>text/plain</content_type><last_modified>2023-03-13T11:04:49.657Z</last_modified></object><object><name>upfile</name><hash>909ef0d762160c163d5bf71adca22ea8</hash><bytes>17</bytes><content_type>text/plain</content_type><last_modified>2023-03-07T05:38:16.622Z</last_modified></object></container>
## END RESPONSE BODY ##
# END RESPONSE #

"Prettified" response body:

<?xml version="1.0" encoding="UTF-8"?>
<container name="example">
  <object>
    <name>cat.png</name>
    <hash>8783c70360231686325c4952c87e5bc4</hash>
    <bytes>24351</bytes>
    <content_type>image/png</content_type>
    <last_modified>2023-09-14T00:11:28.792Z</last_modified>
  </object>
  <object>
    <name>example.txt</name>
    <hash>ce90a5f32052ebbcd3b20b315556e154</hash>
    <bytes>46</bytes>
    <content_type>text/plain</content_type>
    <last_modified>2023-03-06T17:34:12.650Z</last_modified>
  </object>
  <subdir name="exampleprefix1/">
    <name>exampleprefix1/</name>
  </subdir>
  <object>
    <name>meme.png</name>
    <hash>eb1c50662e6a9f64f55386584e483bc5</hash>
    <bytes>990237</bytes>
    <content_type>image/png</content_type>
    <last_modified>2023-09-13T23:52:48.529Z</last_modified>
  </object>
  <subdir name="pathprefix1/">
    <name>pathprefix1/</name>
  </subdir>
  <object>
    <name>testfile</name>
    <hash>18f2ae724cf04ac1b5306f8cf9a6137d</hash>
    <bytes>32</bytes>
    <content_type>text/plain</content_type>
    <last_modified>2023-03-13T11:04:49.657Z</last_modified>
  </object>
  <object>
    <name>upfile</name>
    <hash>909ef0d762160c163d5bf71adca22ea8</hash>
    <bytes>17</bytes>
    <content_type>text/plain</content_type>
    <last_modified>2023-03-07T05:38:16.622Z</last_modified>
  </object>
</container>

`path` == `exampleprefix1/`

# BEGIN REQUEST #
GET /v1/AUTH_NetFire$example/example?format=xml&path=exampleprefix1 HTTP/1.1
Host: us-east1.swift.netfire.com
X-Auth-Token: [REDACTED]
User-Agent: python-swiftclient-4.3.0
# END REQUEST #

# BEGIN RESPONSE #
HTTP/1.1 200 OK
Content-Length: 174
X-Timestamp: 0.00000
X-Container-Object-Count: 7
X-Container-Bytes-Used: 1048347
X-Container-Bytes-Used-Actual: 1064960
X-Storage-Policy: default-placement
X-Storage-Class: STANDARD
Last-Modified: Sat, 30 Sep 2023 08:24:23 GMT
X-Trans-Id: tx000006127b9616959e4ef-006518398a-988dc3-us-east1
X-Openstack-Request-Id: tx000006127b9616959e4ef-006518398a-988dc3-us-east1
Accept-Ranges: bytes
Content-Type: application/xml; charset=utf-8
Date: Sat, 30 Sep 2023 15:06:50 GMT
Connection: close

## BEGIN RESPONSE BODY ##
<?xml version="1.0" encoding="UTF-8"?><container name="example"><subdir name="exampleprefix1/exampleprefix2/"><name>exampleprefix1/exampleprefix2/</name></subdir></container>
## END RESPONSE BODY ##
# END RESPONSE #

"Prettified" response body:

<?xml version="1.0" encoding="UTF-8"?>
<container name="example">
  <subdir name="exampleprefix1/exampleprefix2/">
    <name>exampleprefix1/exampleprefix2/</name>
  </subdir>
</container>

Create/Update an Object ("Upload a File")

To upload a file to a container (technically you're "creating an object" in the container and populating that object's storage with bytes, or replacing the bytes if the object name already exists), a PUT request is performed via the Object URL.

You can optionally provide in your request:

An ETag header containing a lowercase hex representation of the MD5 sum of the object (recommended but not shown)
A Content-Type header containing the content MIME type (RFC 9110 § 8.3) (recommended but not shown)

# BEGIN REQUEST #
PUT /v1/AUTH_NetFire$example/example/pathprefix1/cat.png HTTP/1.1
Host: us-east1.swift.netfire.com
X-Object-Meta-Mtime: 1694664688.000000
X-Auth-Token: [REDACTED]
Content-Length: 24351
User-Agent: python-swiftclient-4.3.0

## BINARY DATA BODY EXPUNGED ##

# END REQUEST #

# BEGIN RESPONSE #
HTTP/1.1 201 Created
ETag: 8783c70360231686325c4952c87e5bc4
Last-Modified: Sat, 30 Sep 2023 16:02:36 GMT
X-Trans-Id: tx0000010c9e014280554a6-006518469c-988dd5-us-east1
X-Openstack-Request-Id: tx0000010c9e014280554a6-006518469c-988dd5-us-east1
Content-Type: text/plain; charset=utf-8
Content-Length: 0
Date: Sat, 30 Sep 2023 16:02:36 GMT
Connection: close
# END RESPONSE #

Get an Object ("Download a File")

An object can be downloaded by performing a GET request against an Object URL, which will retrieve (download) an object (file). Below, the object pathprefix1/cat.png is downloaded from the example bucket.

# BEGIN REQUEST #
GET /v1/AUTH_NetFire$example/example/pathprefix1/cat.png HTTP/1.1
Host: us-east1.swift.netfire.com
X-Auth-Token: [REDACTED]
User-Agent: python-swiftclient-4.3.0
# END REQUEST #

# BEGIN RESPONSE #
HTTP/1.1 200 OK
Content-Length: 24351
Accept-Ranges: bytes
Last-Modified: Sat, 30 Sep 2023 16:02:36 GMT
X-Timestamp: 1696089756.29289
etag: 8783c70360231686325c4952c87e5bc4
X-Object-Meta-Mtime: 1694664688.000000
X-Trans-Id: tx00000cc6d0a42e3c8a28b-0065184a9e-988dd5-us-east1
X-Openstack-Request-Id: tx00000cc6d0a42e3c8a28b-0065184a9e-988dd5-us-east1
Content-Type: image/png
Date: Sat, 30 Sep 2023 16:19:42 GMT
Connection: close

## BINARY DATA BODY EXPUNGED ##

# END RESPONSE #

Copy an Object

An object can be copied to another object without ever needing to be downloaded from NetFire Cloud Storage.

This is done by one of two ways, each of which is shown below.

Copying can optionally be performed conditionally, only if certain conditions match. These conditions are specified via one or more of the following additional RFC 9110-compatible/derived request headers:

If-Modified-Since (Compared against Last-Modified)
If-Unmodified-Since (Compared against Last-Modified)
Copy-If-Match (Compared against ETag)
Copy-If-None-Match (Compared against ETag)

Additionally, the X-Fresh-Metadata header if set to true (default is false) can be used to suppress copying or appending the origin's metadata, and metadata headers can be specified along with the copy request (if X-Fresh-Metadata is true and metadata headers are provided in the copy request, then only those metadata will be applied to the copy. If X-Fresh-Metadata is false or not provided, then the metadata headers in the copy request are appended to the copy).

In both of the below examples, the object pathprefix1/cat.png in the example container is copied to the differentprefix/copycat.png object in the newcontainer bucket.

🚧
The destination container must exist first!
If the destination container does not exist, a 404 will be returned.

📘
Existing references are OK!
You can copy an object to a different name in the same container, or even to the same container and same object name -- the latter of which is an easy way to reset the metadata if none is provided in the copy request.

Using `COPY`

If your language/library/client supports the COPY HTTP method/verb (or custom methods/verbs), it can be done via a COPY on the current/origin/existing/source Object URL with the Destination header set to the destination/new/target container and object name (e.g. Destination: <destination bucket name>/<destination object name>). Note that COPY is not a standard HTTP method but rather part of the WebDAV extension.

# BEGIN REQUEST #
COPY /v1/AUTH_NetFire$example/example/pathprefix1/cat.png HTTP/1.1
Host: us-east1.swift.netfire.com
Destination: /newcontainer/differentprefix/copycat.png
X-Auth-Token: [REDACTED]
X-Fresh-Metadata: false
User-Agent: python-swiftclient-4.3.0
# END REQUEST #

# BEGIN RESPONSE #
HTTP/1.1 201 Created
ETag: 8783c70360231686325c4952c87e5bc4
Last-Modified: Sat, 30 Sep 2023 17:13:45 GMT
X-Copied-From: example/pathprefix1%2Fcat.png
X-Copied-From-Account: example
X-Copied-From-Last-Modified: Sat, 30 Sep 2023 16:02:36 GMT
X-Object-Meta-Mtime: 1694664688.000000
X-Trans-Id: tx0000064a6929cd52e2638-0065185749-988dc3-us-east1
X-Openstack-Request-Id: tx0000064a6929cd52e2638-0065185749-988dc3-us-east1
Content-Type: image/png
Content-Length: 0
Date: Sat, 30 Sep 2023 17:13:45 GMT
Connection: close
# END RESPONSE #

Using `PUT`

If your language/library/client does not support COPY, it can be done by performing a PUT on the destination/new/target Object URL with the X-Copy-From header set to the current/origin/existing/source container and object name (e.g. X-Copy-From: <origin container name>/<origin object name>).

# BEGIN REQUEST #
PUT /v1/AUTH_NetFire$example/differentprefix/copycat.png HTTP/1.1
Host: us-east1.swift.netfire.com
X-Auth-Token: [REDACTED]
X-Copy-from: example/pathprefix1/cat.png
User-Agent: python-swiftclient-4.3.0
# END REQUEST #

# BEGIN RESPONSE #
HTTP/1.1 201 Created
ETag: 8783c70360231686325c4952c87e5bc4
Last-Modified: Sat, 30 Sep 2023 17:37:55 GMT
X-Copied-From: example/pathprefix1%2Fcat.png
X-Copied-From-Account: example
X-Copied-From-Last-Modified: Sat, 30 Sep 2023 16:02:36 GMT
X-Object-Meta-Mtime: 1694664688.000000
X-Trans-Id: tx00000810ef1b77404d3d1-0065185cf3-988dc3-us-east1
X-Openstack-Request-Id: tx00000810ef1b77404d3d1-0065185cf3-988dc3-us-east1
Content-Type: image/png
Content-Length: 0
Date: Sat, 30 Sep 2023 17:37:55 GMT
Connection: close
# END RESPONSE #

Delete an Object ("Delete a File")

An object can be removed from a container by issuing a DELETE request on the Object URL. The object pathprefix1/cat.png is removed from the example bucket below.

# BEGIN REQUEST #
DELETE /v1/AUTH_NetFire$example/example/pathprefix1/cat.png HTTP/1.1
Host: us-east1.swift.netfire.com
X-Auth-Token: [REDACTED]
User-Agent: python-swiftclient-4.3.0
Content-Length: 0
# END REQUEST #

# BEGIN RESPONSE #
HTTP/1.1 204 No Content
X-Trans-Id: tx000005a62bdd3a7afbe97-0065184485-988dc3-us-east1
X-Openstack-Request-Id: tx000005a62bdd3a7afbe97-0065184485-988dc3-us-east1
Content-Type: text/plain; charset=utf-8
Date: Sat, 30 Sep 2023 15:53:42 GMT
Connection: close
# END RESPONSE #

Get Object Metadata

See Object Status. The X-Meta-* headers are the defined metadata, if any, of an object,

Update Object Metadata

To update/change/add metadata to an object, perform a POST request on the Object URL.

Each metadata key should be in the form of an X-Object-Meta-<key name> header. Note that these key/value pairs are entirely arbitrary and their significance, if any, depends entirely on the decision of whichever program is creating/parsing them.

The following request sets a metadata field "Foo-Bar" to "baz" on the object cat.png in the example container. Key/field names should be treated as case-insensitive but values should not.

# BEGIN REQUEST #
POST /v1/AUTH_NetFire$example/example/cat.png HTTP/1.1
Host: us-east1.swift.netfire.com
X-Auth-Token: [REDACTED]
X-Object-Meta-Foo-Bar: baz
User-Agent: python-swiftclient-4.3.0
Content-Length: 0
# END REQUEST #

# BEGIN RESPONSE #
HTTP/1.1 202 Accepted
Content-Length: 0
Accept-Ranges: bytes
X-Trans-Id: tx00000a7f647fe940ac48a-0065186494-988dd5-us-east1
X-Openstack-Request-Id: tx00000a7f647fe940ac48a-0065186494-988dd5-us-east1
Content-Type: text/plain; charset=utf-8
Date: Sat, 30 Sep 2023 18:10:28 GMT
Connection: close
# END RESPONSE #

Swift Object Operations

Object URLs

List Objects

Prefixes, Not Paths

📘
Transitioning to NetFire Cloud Storage can be painless!

JSON

`delimiter` == `/`

`path` == `exampleprefix1/`

XML

`delimiter` == `/`

`path` == `exampleprefix1/`

Create/Update an Object ("Upload a File")

Get an Object ("Download a File")

Copy an Object

🚧
The destination container must exist first!

📘
Existing references are OK!

Using `COPY`

Using `PUT`

Delete an Object ("Delete a File")

Get Object Metadata

Update Object Metadata

Object URLs

List Objects

Prefixes, Not Paths

📘Transitioning to NetFire Cloud Storage can be painless!

JSON

delimiter == /

path == exampleprefix1/

XML

delimiter == /

path == exampleprefix1/

Create/Update an Object ("Upload a File")

Get an Object ("Download a File")

Copy an Object

🚧The destination container must exist first!

📘Existing references are OK!

Using COPY

Using PUT

Delete an Object ("Delete a File")

Get Object Metadata

Update Object Metadata

📘
Transitioning to NetFire Cloud Storage can be painless!

`delimiter` == `/`

`path` == `exampleprefix1/`

`delimiter` == `/`

`path` == `exampleprefix1/`

🚧
The destination container must exist first!

📘
Existing references are OK!

Using `COPY`

Using `PUT`