Store Files – Cloud

Authentication

All requests to the Files Cloud API should be signed with an OAuth token.

Methods

GET /api/file_storage/v1

The root of the files REST API. Returns a User Representation for this user.:

{
    "resource_path": "",
    "user_id": 9999,
    "visible_name": "Fred Flintstone",
    "max_bytes": 123456789,
    "used_bytes": 0,
    "root_node_path": "/~/Ubuntu One", (When including user folders)
    "user_node_paths": [<list of volume folder URIs>,]
}
GET /api/file_storage/v1/(volume)/(path)

Get metadata about a node.

Parameters:
  • volume – the volume containing the file (e.g. ~/Ubuntu One).
  • path – the path to the node within the volume
Query Parameters:
 
  • include_children – if set to true, include metadata about direct children in the response.

A node is a file or a folder. GETting an existing node returns a Node Representation for this node.

All node resources exist in the root directory of a volume. Thus they are all prefixed by the volume path.

Some items are only settable on creation (they are ignored on change), some are only changeable for an existing node (they are ignored on creation), and some are system-defined and cannot be set by API users at all.

Note that a directory has a content_path. This means that you can PUT a new file with content into that directory (see below) by PUTting to CONTENT_ROOT + <directory.content-path> + ‘/’ + filename.ext.

CONTENT_ROOT is the root of the files API itself, /api/file_storage/v1/, but temporarily it should be set to https://files.one.ubuntu.com. (This note will be removed when this is fixed.):

{
    "resource_path": The path to this resource,
    "kind": "file|directory", (ignored on change)
    "path": the path of the node relative to the volume, (ignored on creation)
    "is_public": true|false, (ignored on creation; files only)
    (the following are defined by the system and can't be changed)
        "parent_path": The path to the parent directory resource,
        "volume_path": The path to the volume resource,
        "key": nodekey,
        "when_created": when the node was created,
        "when_changed": node.when_last_modified,
        "generation": generation,
        "generation_created": generation_created,
        "content_path": path for GET & PUT content,
      (Files Only)
        "hash": The current hash of the file,
        "public_url": public URL,
        "size": node.size,
      (Directories Only)
        "has_children": True|False,
        "is_root": True|False,
        "children": [Node Representations of child nodes]
}
PUT /api/file_storage/v1/(volume)/(path)

Create, change, or rename a file or folder.

Parameters:
  • volume – the volume containing the file (e.g. ~/Ubuntu One).
  • path – the path to the node within the volume

The body of the request must contain a Node Representation as JSON, and content type of application/json.

Creating:

{
  "kind": "file"|"directory"
}
  • PUTting with {“kind”:”directory”} or {“kind”:”file”} to a new path (one not under an existing volume) fails and throws an error.
  • PUTting with {“kind”:”directory”} to a path under an existing volume creates a folder and all required parent folders, up to the root of the volume.
  • PUTting with {“kind”:”file”} to a path under an existing volume creates the file and all required parent folders, up to the root of the volume.
  • Note that PUTting with {“kind”:”file”} creates an empty file and is not very useful and therefore not recommended. Files should be PUT with content (see below).

Magic uploads:

This API supports PUTting a file without actually sending the content. You can send a calculated hash of the content with the create request, and if the content is already available in Ubuntu One, the file will be “uploaded” without actually having to send the content on the wire, and the file created correctly in the user’s storage exactly as if it had been conventionally uploaded. This is referred to as a “magic upload”. It is useful to attempt a magic upload before sending file content, because it’s normally much faster to do so, and then fall back to PUTting the content as normal (see below).

To do a magic upload, add two new keys to the PUT body:

{
  "kind": "file",
  "hash": "sha1:" + sha1(file_content),
  "magic_hash": "magic_hash:" + sha1("Ubuntu One" + file_content)
}

If the magic upload succeeds and the file is created in the user’s Ubuntu One storage, the PUT will return a status code of 200 or 201. If it fails, it will return a status code of 400, and body {"error": "The content could not be reused."}

Note that a magic upload may fail even if the content is present in Ubuntu One; you must always be prepared to do a full upload of the content if a magic upload fails.

Changing:

{
  "is_public": true|false
}

Publishing a file will give it a public URL where that file can be retrieved by anyone without access controls. Directories cannot be published.

Renaming:

{
  "path": new path
}

The file will be moved/renamed to the new path. The destination is a path within the same volume. Files can not be moved from one volume to another.

PUTting a node returns the full new Node Representation of the node.

DELETE /api/file_storage/v1/(volume)/(path)

Delete the specified file or folder. Deleting a folder deletes its contents.

Parameters:
  • volume – the volume containing the file (e.g. ~/Ubuntu One).
  • path – the path to the node within the volume
GET /api/file_storage/v1/(content_path)

Get the content of an existing file.

Parameters:
  • content_path – the content path specified in the metadata for the node.

(Note caveat above about CONTENT_ROOT being temporarily different.)

PUT /api/file_storage/v1/(content_path)

PUT a new file, with content, in one action, or overwrite content of an existing file.

Parameters:
  • content_path – either the content path specified for an existing file, or the content path for a directory with the new file’s name appended.

The body of the PUT request is the content of the file. You must specify a Content-Length for the request body, and should specify a Content-Type.

Note that you cannot PUT a new file with content and alter its attributes at the same time.

Note also that content_paths may not be rooted under the API root, and may change without warning, so they must be read from the API and not hardcoded. (Note caveat above about CONTENT_ROOT being temporarily different.)

See “magic uploads” above for a way to attempt uploading a file without sending the content on the wire.

GET /api/file_storage/v1/public_files

Get a list of all the public files published by the user (i.e. ones where is_public is set to true).

The result will be a JSON formatted list of node representations in the form you would get by issuing a GET request on each file individually.

GET /api/file_storage/v1/volumes

Return a JSON list of Volume Representations, one for each volume. A volume is a synced folder, or the Ubuntu One folder, owned by the user. Note that all volume paths begin with ~.:

{
   "resource_path": "/volumes/~/Photos/SyncedWithUbuntuOne",
   "type": "udf", (can be "udf" or "root")
   "key": "Ahcbedalsdesx",
   "path": "~/Photos/SyncedWithUbuntuOne", (volume path)
   "generation": 0,
   "when_created": <timestamp>
   "node_path": "/~/Photos/SyncedWithUbuntuOne", (the root path for node representations for files/folders in this volume)
   "content_path": "/content/~/Photos/SyncedWithUbuntuOne" (the root path for content for files in this volume)
}
GET /api/file_storage/v1/volumes/(volume)

Return a Volume Representation for the specified volume.

Parameters:
  • volume – the volume containing the file (e.g. ~/Ubuntu One).
PUT /api/file_storage/v1/volumes/(volume)

Create a new volume. Note that volumes cannot be nested: a volume cannot be created inside another volume.

Parameters:
  • volume – the volume containing the file (e.g. ~/Ubuntu One).

A volume with path ~/foo/bar/baz will be synced to an Ubuntu desktop as /home/username/foo/bar/baz.

DELETE /api/file_storage/v1/volumes/(volume)

Delete an existing volume, and all contents.

Parameters:
  • volume – the volume containing the file (e.g. ~/Ubuntu One).