Revision as of 12:30, 11 March 2011

The File API is a general-purpose web server API for browsing and manipulating files and directories over HTTP. This API is much simpler and less powerful than [1]. Notably it lacks any capabilities for locking and employs only the basic GET/PUT/POST HTTP methods. It also uses JSON as the default representation rather than XML. This makes the API easier for servers to implement and for JavaScript clients to use, but may not be suitable for all applications.

On success, the response body contains the raw file contents. A 304 response may be used to indicate an unchanged file when a conditional get is performed (such as using If-None-Match in conjunction with an ETag from a previous response).

Getting file metadata

Overview

To retrieve metadata about the file, send a GET request to the file location with the "?parts=meta" query

Note that changing the contents of a non-existing file is not permitted. Files are created via POST operations rather than a PUT. It is recommended that file changes be accompanied by the ETag of the resource state that was modified in the If-Match header. This prevents overwriting changes made by other clients since the resource was last retrieved. A 412 response indicates that an attempt was made to change a file that has been modified since it was last retrieved.

Changing file metadata

Overview

A file's metadata can be updated by performing a PUT to the file's location with the ?parts=meta query added.

Note that only the attributes present in the request are modified. I.e., this operation performs a change on the specified attributes of the resource, but leaves all other existing attributes untouched. This prevents a client from overriding attribute values they didn't know about.

Changing metadata and contents

Overview

A file's metadata and contents can be updated in a single request using a multi-part request body.

Note that only the attributes present in the request are modified. I.e., this operation performs a change on the specified attributes of the resource, but leaves all other existing attributes untouched. This prevents a client from overriding attribute values they didn't know about.

Actions on directories

Getting directory metadata

Overview

The default GET behavior for directories is to return a metadata representation of the directory.

The depth parameter controls what depth of children to include in the response.

Creating files and directories

Notes on POST method

In all cases, the POST method is a request to create a resource that is a direct descendant of the request URI. The Slug header, if present, indicates the name of the new resource. If a resource was successfully created, the method returns a 201 response. If an existing resource was replaced, a 200 response is used to indicate success. The Location header of the response indicates the URI of the created or replaced resource.

The entity body, if present, indicates attributes to be applied to the created resource.
Attributes in the request bod must conform to the file JSON representation. Any attributes that are not present will assume default values. If the name of the new resource is not specified by either the Slug header or by indicating a source resource to be copied or moved, then the entity body must minimally contain the Name attribute.

If the X-Create-Options header is present, it may indicate that the resource to be created is to be copied or moved from some existing resource. In this case the entity body must contain a Location attribute specifying the source resource to be copied or moved. If the copy or move option is specified but there is no location in the entity body, then a response code of 400 is used to indicate a bad request. A 400 request may also indicate an illegal combination of X-Create-Options values (such as "copy,move"). The value of the X-Create-Options field is interpreted as a comma-delimited series of options. Unrecognized options are ignored to allow for compatibility with future versions of this specification.

A 403 response indicates that the request attempted to copy or move a resource onto itself or a descendant of itself.

An X-Create-Options value of "no-overwrite" indicates that the operation MUST fail if the resource to be created already exists. If this value is not present then any existing resource will be overwritten. A 412 return code is used to indicate that the "no-overwrite" option was specified and the destination resource already exists.

The name of the created file is taken from the Slug header value. The response body contains metadata information about the newly created file.

Creating a file with contents

Creating a file and providing contents is not currently supported in a single request. The client must first create a file with a POST as in the previous section, and then perform a PUT on the location specified in the POST response to provide file contents.

Copy, move, and delete

Deleting a file or directory

Overview

To delete a file or directory, send DELETE to the resource's location.

Use of the If-Match header is recommended to avoid deleting contents that have been modified by another party since the file was last retrieved. Deleting a non-existent resource succeeds with no effect (returns 204 OK).

Copying a file or directory

Overview

Copying is similar in form to file or directory creation. The post is performed against the parent directory where the new file or directory is to be created. The source of the copy is specified in the request body. The X-Create-Options header differentiates copying from simple file creation.

Moving a file or directory

Overview

Moving is similar in form to file or directory creation. The post is performed against the parent directory where the new file or directory is to be created. The source of the move is specified in the request body. The X-Create-Options header differentiates moving from simple file creation.

JSON representations

File

The file API uses the following JSON representation for file and directory objects in request and response bodies. Required fields are shown in bold. A client cannot rely on the existence of non-required attribute in a file representation from a given Orion server.

file character set (method used to convert the file bytes into characters)

ContentType

String

MIME content type

ContentLength

long

The length of the file in bytes

File Attributes

If present, the Attributes object within the JSON representation of the file may support the following values:

Field

Data type

Value

ReadOnly

boolean

Whether the file is modifiable

Executable

boolean

Whether the file is executable

Hidden

boolean

Whether the file is hidden

Archive

boolean

Whether the file has the archive bit set

SymbolicLink

boolean

Whether the file is a symbolic link

File Children

JSON representations of files (directories) may include a Children attribute. The value of this attribute is an array of file objects, one for each child of the directory. Those children may in turn include Children attributes for listing their own children. In this way, a JSON file representation may represent an entire file system sub-tree.

File Parents

JSON representations of files may include a Parents attribute. The value of this attribute is an array of file objects, one for each parent. The array is ordered so that the first element is the immediate parent, the second entry is the grandparent, etc. Note that it is not possible in all cases to accurately represent the parents of a file. For example the target of a symbolic link may be seen to have multiple direct parents. The purpose of the Parents attribute is to allow for logical navigation (such as a ".." link to a file's parent), rather than providing a canonical physical description of the file hierarchy. For example, deleting the parent of a file is not guaranteed to delete the file, due to the possibility of other parents of that file continuing to exist.