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.
Difference between revisions of "Orion/Server API/Site Configuration API"
< Orion | Server API
m (→Getting all site configurations: add example response) |
m (More doc) |
||
Line 11: | Line 11: | ||
* '''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.) | * '''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.) | ||
+ | Whenever a 4xx status code is returned, the response body will contain detailed information about the error. See [[Server_API#Exception_Handling]] for a full explanation. | ||
== Basic Actions == | == Basic Actions == | ||
Line 44: | Line 45: | ||
"Workspace": "A" | "Workspace": "A" | ||
} | } | ||
− | ] | + | ]} |
− | } | + | | explain = On success, the response body contains the JSON representation of all the logged-in user's site configurations. The representation is of type [[#Site configurations list]]. |
− | | explain = | + | |
}} | }} | ||
Line 60: | Line 60: | ||
| respbody = | | respbody = | ||
TBD | TBD | ||
− | | explain = | + | | explain = On success, the response body contains the JSON representation of all the logged-in user's site configurations. The representation is of type [[#Site configurations list]]. |
}} | }} | ||
Line 201: | Line 201: | ||
− | == | + | == Site configurations list == |
{| cellspacing="0" border="1" style="text-align: center; width: 90%;" | {| cellspacing="0" border="1" style="text-align: center; width: 90%;" | ||
|- align="center" style="background: none repeat scroll 0% 0% rgb(204, 204, 255); padding: 0pt 5px;" | |- align="center" style="background: none repeat scroll 0% 0% rgb(204, 204, 255); padding: 0pt 5px;" |
Revision as of 14:23, 28 February 2011
Progress is being tracked in bug 337212.
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.)
Whenever a 4xx status code is returned, the response body will contain detailed information about the error. See Server_API#Exception_Handling for a full explanation.
Basic 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: application/json; charset=UTF-8 Content-Length: 333 { "SiteConfigurations": [ { "HostingStatus": { "Status": "stopped" }, "Id": "G", "Location": "http://localhost:8080/site/G", "Mappings": [ { "Source": "/", "Target": "/I" }, { "Source": "/github", "Target": "http://mamacdon.github.com" } ], "Name": "SiteConfig", "Workspace": "A" } ]}
- Detailed Explanation
- On success, the response body contains the JSON representation of all the logged-in user's site configurations. The representation is of type #Site configurations list.
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
- On success, the response body contains the JSON representation of all the logged-in user's site configurations. The representation is of type #Site configurations list.
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).
Other Actions
Starting a site configuration
Stopping a site configuration
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 | The URL where the started site configuration can be accessed. Each element of the array is a Mappings object (see #Mapping). |
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. |
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 of Source paths:
"/"
would map requests for the root of the site (/)."/index.html"
would map requests for the index page (/index.html) of the site.
Examples of Target paths:
"/B/foo/bar"
, where B is the Id of a project."http://o.aolcdn.com/dojo/1.5/dojo/dojo.xd.js"
.
Site configurations list
Field | Data type | Value |
---|---|---|
SiteConfigurations | Array | The site configurations. Each element of the array is a site configuration object (see #Site_configuration). |
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. |