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.
Orion/Server API/Site Configuration API
< Orion | Server API
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).
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 of Mappings | The URL where the started site configuration can be accessed. |
A Mapping
List of site configurations
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. |