Orion/Server API/Site Configuration API

Work in progress

The Site Configuration API is a web server API for creating, editing, starting and stopping site configurations.

Status codes

The following HTTP response status codes are used by this API:

• 400 Bad Request when any of the request URI, request headers, or request body is malformed.
• 404 Not Found when the site configuration Id given in the request URI does not exist.
• 409 Conflict when a request indicated an action should be taken on a site configuration, but the site configuration is not in a state that allows the action. (For example, an attempt to start a site configuration that is already started.)

CRUD Actions

Getting all site configurations

Overview

To retrieve the working tree status of a project, send a GET request to the git status location.

HTTP Method

GET

Example Request

GET /site

  

Example Response

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

TBD

Detailed Explanation

TBD.

Getting a single site configuration

Overview

To retrieve changes between selected commits, commit and working tree, and so on. Send a GET request to the git diff location.

HTTP Method

GET

Example Request

GET /site/siteConfigurationId

  

Example Response

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

TBD

Detailed Explanation

TBD.

Creating a site configuration

Overview

Overview

HTTP Method

POST

Example Request

POST /site 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/MyProj/myfolder",
"ETag" : "35fd43td3",
"LocalTimeStamp" : "01234345009837",
"Directory" : "true"
"Attributes" : {
"ReadOnly" : "false",
"Executable" : "true"
}
}

Detailed Explanation

See Notes on POST method for further details.

Editing a site configuration

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/MyProj/myfile.txt 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/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.

Deleting a site configuration

Overview

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

HTTP Method

DELETE

Example Request

DELETE /file/myfile.txt 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).

JSON representations

Site configuration

Field	Data type	Value
Id	string	Globally unique id of the site configuration.
Location	string	The URL of this site configuration resource
Name	string	The URL where the started site configuration can be accessed.
Workspace	string	The Id of the Workspace that the site configuration is associated to.
Mappings	Array of Mappings	The URL where the started site configuration can be accessed.

A Mapping

Field	Data type	Value
Source	string	The source path. Begins with a slash, and gives a request path on the running site configuration which will be mapped to the Target path. Examples: "/" would map requests for the root of the site (/). "/index.html" would map requests for the index page (/index.html) of the site.
Target	string	The path to which requests matching the Source field will be mapped. This can be an absolute path to a resource in the Orion user's workspace. Alternately, it may be a web URL. Examples: "/B/foo/bar", where B is the Id of a project. "http://o.aolcdn.com/dojo/1.5/dojo/dojo.xd.js".

Hosting Status

If present, the HotingStatus object within the JSON representation of the site configuration may support the following values:

Field	Data type	Value
Status	string	stopped
URL	string	The URL where the started site configuration can be accessed.