Notice: This Wiki is now read only and edits are no longer 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
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:
- 200 OK for most requests that succeeded.
- 201 Created when a site configuration was created successfully.
- 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 all the logged-in-user's site configuration, send GET to the site config API.
- 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 a single site configuration, send GET to its location.
- HTTP Method
- GET
- Example Request
GET /site/<siteConfigurationId>
- Example Response
HTTP/1.1 200 OK
Content-Type: TBD
Content-Length: TBD
TBD
- Detailed Explanation
- On success, the response body contains the JSON representation of the site configuration. The representation is of type #Site configuration.
Creating a site configuration
- Overview
- To create a site configuration, send POST to the site configuration API.
- HTTP Method
- POST
- Example Request
POST /site
Slug: My site configuration
{
"Workspace" : "A"
}
- Example Response
HTTP/1.1 201 Created
TBD
- Detailed Explanation
- The Slug header contains the name of the site configuration to be created. If the Slug header is not present, then there must instead be a Name field in the request body giving the name.
The request body must contain a Workspace field giving the workspace id that the site configuration is associated to. Minimally, the name and workspace are required to create a site configuration. Other fields may optionally be included; see #Site configuration.
On success, the response body contains the representation of the site configuration that was created. The representation type is #Site configuration.
Editing a site configuration
- Overview
- To update one or more fields of a site configuration, send PUT to the site configuration's location.
- HTTP Method
- PUT
- Example Request
PUT /site/<siteConfigurationId>
Content-Type: application/json
{
"Name": "New name for my site configuration" }
- Example Response
HTTP/1.1 HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 132
ETag: "35fd43td3"
TBD
- Detailed Explanation
- The request body contains the fields of the site configuration that will be updated and their values. If Name or Workspace fields are provided, then they must not be empty.
On success, the response body contains the updated site configuration. The representation type of the response body is #Site configuration.
Deleting a site configuration
- Overview
- To delete a site configuration, send DELETE to the site configuration's location.
- HTTP Method
- DELETE
- Example Request
DELETE /site/<siteConfigurationId>
- Example Response
HTTP/1.1 200 OK
- Detailed Explanation
- Successful deletion is indicated by a 200 OK response. Deleting a non-existent resource fails with a 404 Not Found response.
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. |