Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

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.

Back to the top