Orion/Server API/File API

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.

Actions on files

Getting file contents

Overview

To retrieve the contents of a file, send a GET request to the file resource's location.

HTTP Method

GET

Example Request

GET /file/{:workspace_id}/{:project_dir}/{:file_path}

  

Example Response

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 22

This is the contents

Detailed Explanation

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

HTTP Method

GET

Example Request

GET /file/{:workspace_id}/{:project_dir}/{:file_path}?parts=meta HTTP/1.1
Orion-Version: 1.0

  

Example Response

HTTP/1.1 200 OK HTTP/1.1
Content-Type: application/json
Content-Length: 132
ETag: "35fd43td3"

{
"Name" : "myfile.txt",
"Location" : "http://example.com/file/user-OrionContent/MyProj/myfile.txt",
"ETag" : "35fd43td3",
"Directory" : false,
"LocalTimeStamp" : "01234345009837",
"Charset" : "UTF-8",
"ContentType" : "text/plain",
"Attributes" : {
  "ReadOnly" : false,
  "Executable" : true
}
}

Detailed Explanation

On success, the response body contains a representation of the file's metadata. By default the response is a JSON representation.

Getting file metadata and contents

Overview

Both metadata and file contents can be retrieved in a single request, in order to reduce round trips.

HTTP Method

GET

Example Request

GET /file/{:workspace_id}/{:project_dir}/{:file_path}?parts=meta,body HTTP/1.1
Orion-Version: 1.0

  

Example Response

HTTP/1.1 HTTP/1.1 200 OK
Content-Type: multipart/related; boundary="BOUNDARY"
ETag: "35fd43td3"
--BOUNDARY
Content-Type: application/json

{
"Name" : "myfile.txt",
"Location" : "http://example.com/file/user-OrionContent/MyProj/myfile.txt",
"ETag" : "35fd43td3",
"Directory" : false,
"LocalTimeStamp" : "01234345009837",
"Charset" : "UTF-8",
"ContentType" : "text/plain",
"Attributes" : {
   "ReadOnly" : false,
   "Executable" : true
}
}

--BOUNDARY
Content-Type: text/plain

This is the contents 

--BOUNDARY

Detailed Explanation

The file's metadata and contents are returned as a single multi-part response.

Setting file contents

Overview

The contents of an existing file can be replaced with a simple PUT to the file resource's location.

HTTP Method

PUT

Example Request

PUT /file/{:workspace_id}/{:project_dir}/{:file_path} HTTP/1.1
Orion-Version: 1.0
If-Match: "35fd43td2"
Content-Type: text/plain

This is the new contents  

Example Response

HTTP/1.1 HTTP/1.1 200 OK 
Content-Type: application/json
Content-Length: 132
ETag: "35fd43td3"

{
"Name" : "myfile.txt",
"Location" : "http://example.com/file/user-OrionContent/MyProj/myfile.txt",
"ETag" : "35fd43td3",
"Directory" : false,
"LocalTimeStamp" : "01234345009837",
"Charset" : "UTF-8",
"ContentType" : "text/plain",
"Attributes" : {
   "ReadOnly" : false,
   "Executable" : true
}
}

Detailed Explanation

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.

Modifying file contents with a diff

Overview

The contents of an existing file can be modified by sending a POST (with X-HTTP-Method-Override) to the file resource's location.

HTTP Method

POST

Example Request

POST /file/{:workspace_id}/{:project_dir}/{:file_path} HTTP/1.1
Orion-Version: 1.0
If-Match: aaf4c61
Content-Type: application/json;charset=UTF-8
X-HTTP-Method-Override: PATCH

{"diff":[{"start":5,"end":5,"text":" world"}]}  

Example Response

HTTP/1.1 HTTP/1.1 200 OK 
Content-Type: application/json; charset=UTF-8
ETag: 2aae6c35c

{
  "Name" : "myfile.txt",
  "Location" : "http://example.com/file/user-OrionContent/MyProj/myfile.txt",
  "ETag" : "2aae6c35c",
  "Directory" : false,
  "Length": 11,
  "LocalTimeStamp" : 1456416151000,
  "Attributes" : {
    "ReadOnly" : false,
    "Executable" : false,
    "SymLink" : false
  }
}

Detailed Explanation

A JSON diff allows the client to modify file contents without transferring the entire file over the network. The diff shown above inserts the text ", world" at offset 5 in myfile.txt. 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.

Setting file contents with different HTTP input

Overview

The contents of an existing file can be replaced with the content from an arbitrary URL with a simple PUT to the file resource's location. In the example below, the content of the resource at /file/MyProj/myfile.txt will be replaced with the content of the resource at http://example.com/file/source/sourcefile.txt.

HTTP Method

PUT

Example Request

PUT /file/{:workspace_id}/{:project_dir}/{:file_path}?source=http://example.com/file/source/sourcefile.txt HTTP/1.1
Orion-Version: 1.0
If-Match: "35fd43td2"
Content-Type: text/plain

  

Example Response

HTTP/1.1 HTTP/1.1 200 OK 
Content-Type: application/json
Content-Length: 132
ETag: "35fd43td3"

{
"Name" : "myfile.txt",
"Location" : "http://example.com/file/user-OrionContent/MyProj/myfile.txt",
"ETag" : "35fd43td3",
"Directory" : false,
"LocalTimeStamp" : "01234345009837",
"Charset" : "UTF-8",
"ContentType" : "text/plain",
"Attributes" : {
   "ReadOnly" : false,
   "Executable" : true
}
}

Detailed Explanation

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.

HTTP Method

PUT

Example Request

PUT /file/{:workspace_id}/{:project_dir}/{:file_path}?parts=meta HTTP/1.1
Orion-Version: 1.0
Content-Type: application/json

{
"Attributes" : {
   "ReadOnly" : true
}
}  

Example Response

HTTP/1.1 204 OK

Detailed Explanation

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.

HTTP Method

PUT

Example Request

PUT /file/{:workspace_id}/{:project_dir}/{:file_path}?parts=meta,body HTTP/1.1
Orion-Version: 1.0
Content-Type: application/json

{
"Name" : "myfile.txt",
"Attributes" : {
   "ReadOnly" : true
}
}

--BOUNDARY
Content-Type: text/plain

This is the new contents 

--BOUNDARY  

Example Response

HTTP/1.1 204 OK

Detailed Explanation

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.

HTTP Method

GET

Example Request

GET /file/{:workspace_id}/{:project_dir}/{:folder_path} HTTP/1.1
Orion-Version: 1.0

  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 232

{
"Name" : "myfolder",
"Location" : "http://example.com/file/user-OrionContent/MyProj/myfolder",
"ChildrenLocation" : "http://example.com/file/user-OrionContent/MyProj/myfolder?depth=1",
"LocalTimeStamp" : "01234345009837",
"Directory" : true
"Attributes" : {
   "ReadOnly" : false,
   "Executable" : true
}
}

Detailed Explanation

The base behavior on GET does not return information about children. The depth parameter can be used to obtain information on children.

Changing directory metadata

Overview

Overview

HTTP Method

PUT

Example Request

PUT /file/{:workspace_id}/{:project_dir}/{:folder_path}
Orion-Version: 1.0
Content-Length: 44
Content-Type: application/json

{
"Attributes" : {
   "ReadOnly" : true
}
}  

Example Response

HTTP/1.1 204 OK

Detailed Explanation

The above example sets the read-only attribute to true, and leaves all other directory attributes unchanged.

Listing directory contents

Overview

Overview

HTTP Method

GET

Example Request

GET /file/{:workspace_id}/{:project_dir}/{:folder_path}?depth=1 HTTP/1.1
Orion-Version: 1.0

  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 132

{
"Name" : "myfolder",
"Location" : "http://example.com/file/user-OrionContent/MyProj/myfolder",
"LocalTimeStamp" : "01234345009837",
"Directory" : true
"Attributes" : {
   "ReadOnly" : false,
   "Executable" : true
},
"Children" : [  
{
   "Name" : "myfile.txt",
   "Location" : "http://example.com/file/user-OrionContent/MyProj/myfolder/myfile.txt",
   "Directory" : false
}
]
}

Detailed Explanation

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 body 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.

Creating a directory

Overview

Overview

HTTP Method

POST

Example Request

POST /file/{:workspace_id}/{:project_dir}/{:parent_folder_path} HTTP/1.1
Orion-Version: 1.0
Content-Length: 48
Content-Type: application/json
Slug: myfolder

{
 "Name" : "myfolder",
 "Directory" : true
}  

Example Response

HTTP/1.1 201 OK

{
"Name" : "myfolder",
"Location" : "http://example.com/file/user-OrionContent/MyProj/myfolder",
"ETag" : "35fd43td3",
"LocalTimeStamp" : "01234345009837",
"Directory" : true
"Attributes" : {
   "ReadOnly" : false,
   "Executable" : true
}
}

Detailed Explanation

See Notes on POST method for further details.

Creating an empty file

Overview

A new file is created by performing a POST against the location of the parent directory the file is to be created in.

HTTP Method

POST

Example Request

POST /file/{:workspace_id}/{:project_dir}/{:parent_folder_path} HTTP/1.1
Orion-Version: 1.0
Slug: myfile.txt

  

Example Response

HTTP/1.1 201 Created
Location: http://example.com/file/MyProj/myfile.txt
ETag: "35fd43td3"
Content-Type: application/json

{
"Name" : "myfile.txt",
"Location" : "http://example.com/file/user-OrionContent/MyProj/myfile.txt",
"Charset" : "UTF-8",
"ContentType" : "text/plain",
"LocalTimeStamp" : "01234345009837",
"Directory" : false
"Attributes" : {
   "ReadOnly" : false,
   "Executable" : true
}
}

Detailed Explanation

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.

HTTP Method

DELETE

Example Request

DELETE /file/{:workspace_id}/{:project_dir}/{:file_path} HTTP/1.1
Orion-Version = 1.0
If-Match: 980sdfhsdf8f

  

Example Response

HTTP/1.1 204 OK

Detailed Explanation

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.

HTTP Method

POST

Example Request

POST /file/{:workspace_id}/{:project_dir}/{:parent_folder_path} HTTP/1.1
Orion-Version: 1.0
Content-Length: 144
Content-Type: application/json
Slug: destination.txt
X-Create-Options: copy

{
"Location" : "http://example.com/file/user-OrionContent/MyProj/source.txt"
}  

Example Response

HTTP/1.1 201 Created
Location: http://example.com/file/user-OrionContent/MyProj/destination.txt
ETag: "35fd43td3"
Content-Type: application/json

{
"Name" : "destination.txt",
"Location" : "http://example.com/file/user-OrionContent/MyProj/destination.txt",
"ETag" : "35fd43td3",
"LocalTimeStamp" : "01234345009837",
"Directory" : true
"Attributes" : {
   "ReadOnly" : false,
   "Executable" : true
}
}

Detailed Explanation

See Notes on POST method for further details.

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. Renaming a file or directory is equivalent to a move, and performed in the same way.

HTTP Method

POST

Example Request

POST /file/{:workspace_id}/{:project_dir}/{:parent_folder_path} HTTP/1.1
Orion-Version: 1.0
Content-Length: 144
Content-Type: application/json
Slug: destination.txt
X-Create-Options: move

{
"Location" : "http://example.com/file/user-OrionContent/MyProj/source.txt"
}  

Example Response

HTTP/1.1 201 Created
Location: http://example.com/file/user-OrionContent/MyProj/destination.txt
ETag: "35fd43td3"
Content-Type: application/json

{
"Name" : "destination.txt",
"Location" : "http://example.com/file/user-OrionContent/MyProj/destination.txt",
"ETag" : "35fd43td3",
"LocalTimeStamp" : "01234345009837",
"Directory" : true
"Attributes" : {
   "ReadOnly" : false,
   "Executable" : true
}
}

Detailed Explanation

See Notes on POST method for further details.

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.

Field	Data type	Value
Name	String	String file name
Directory	Boolean	true for a directory and false for a file
ETag	String	Opaque token representing a unique state of this file or directory
LocalTimeStamp	long	last modified time in milliseconds since January 1, 1970
Location	String	File location URL (see Orion/Server API#Resource Locations)
ChildrenLocation	String	Directory children location URL (see Orion/Server API#Resource Locations)
Attributes	Object	The file's permission attributes (see #File Attributes)
Children	Array of Object	The children of a directory (see #File Children)
Parents	Array of Object	The parents of a file or directory (see #File Parents)
Charset	String	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.

The X-Create-Options header

The X-Create-Options header consists of a comma-delimited list of options controlling how a resource is to be created (see Notes on POST method). If an X-Create-Options header is provided, it may take one of the following basic options:

• copy
• move

The following option may also appear in addition to copy or move:

• no-overwrite

The ordering of the options does not matter and any unrecognized options are ignored. However, invalid combinations of recognized options (such as "copy,move") will yield an error 400 response.

References

For details on server API resource locations, see Orion/Server API#Resource Locations.