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.
Difference between revisions of "Orion/Server API/Site Configuration API"
(Add config section) |
m (→Setting up hosting) |
||
Line 6: | Line 6: | ||
== Setting up hosting == | == Setting up hosting == | ||
− | To set up hosting (required in order to use the [[#Starting a site configuration|start]] and [[#Stopping a site configuration| | + | To set up hosting (required in order to use the [[#Starting a site configuration|start]] and [[#Stopping a site configuration|stop]] actions), you must launch Orion with a special JVM argument that tells it what virtual host names are available: |
* '''<code>org.eclipse.orion.server.hosting.virtualHosts</code>''' | * '''<code>org.eclipse.orion.server.hosting.virtualHosts</code>''' | ||
− | The argument's value is a string with the form <code>domains=domain-list</code> or <code>IPs=ipList</code>, where <code>domainList</code> is a comma-separated list of domains (which may include wildcards), and <code>ipList</code> is a comma-separated list of IP addresses. | + | The argument's value is a string with the form <code>domains=domain-list</code> or <code>IPs=ipList</code>, where <code>domainList</code> is a comma-separated list of domains (which may include wildcards), and <code>ipList</code> is a comma-separated list of IP addresses. The supplied values will be allocated to sites |
− | + | so they, must be aliases for the Orion server. <!-- TODO more exposition here --> | |
− | Examples: | + | '''Examples:''' |
; <code>org.eclipse.orion.server.hosting.virtualHosts=IPs=127.0.0.2,127.0.0.3</code> | ; <code>org.eclipse.orion.server.hosting.virtualHosts=IPs=127.0.0.2,127.0.0.3</code> | ||
: Makes 2 IPs available for allocation. | : Makes 2 IPs available for allocation. | ||
Line 21: | Line 21: | ||
;<code>org.eclipse.orion.server.hosting.virtualHosts=domains=*.myorion.net</code> | ;<code>org.eclipse.orion.server.hosting.virtualHosts=domains=*.myorion.net</code> | ||
− | : Makes all of <code>*.myorion.net</code> available for allocation. | + | : Makes all of <code>*.myorion.net</code> available for allocation. Hosted sites will be given subdomains, for example <code>site1.myorion.net</code>, <code>site2.myorion.net</code>, etc. |
; <code>org.eclipse.orion.server.hosting.virtualHosts=IPs=127.0.0.2,domains=*.myorion.net</code> | ; <code>org.eclipse.orion.server.hosting.virtualHosts=IPs=127.0.0.2,domains=*.myorion.net</code> | ||
: Equivalent to the previous example; when both domains and IPs are provided, domains are given priority. | : Equivalent to the previous example; when both domains and IPs are provided, domains are given priority. | ||
+ | |||
+ | |||
+ | ==== Note about self-hosting==== | ||
+ | If you just want to try out hosting on your locally-running Orion server, and remote users will never need to access your hosted site, read this section. | ||
+ | |||
+ | It's usually sufficient to supply a list of 127.x.x.x addresses: | ||
+ | |||
+ | * <code>org.eclipse.orion.server.hosting.virtualHosts=ips=127.0.0.2,127.0.0.3,127.0.0.4</code> | ||
+ | ... and so on. On most platforms, any 127.x.x.x address is an alias for localhost. Mac OS X is a notable exception to this rule; OS X users must manually add an alias to any 127.x.x.x addresses they want to use for hosting, by running commands like this from a Terminal window: | ||
+ | |||
+ | * <code>sudo ifconfig lo0 alias 127.0.0.2 up</code> | ||
+ | |||
+ | Windows users can create aliases using the [[http://en.wikipedia.org/wiki/Hosts_file hosts file]] if desired. | ||
== Status codes == | == Status codes == |
Revision as of 17:19, 4 March 2011
Progress is being tracked in Bug 335789.
The Site Configuration API is a web server API for creating, editing, starting and stopping site configurations. A site configuration is a set of URI-mapping rules that allow users to run files from their Orion workspace, or remote URLs, as a "hosted site" — that is, a virtual host on an Orion server.
Setting up hosting
To set up hosting (required in order to use the start and stop actions), you must launch Orion with a special JVM argument that tells it what virtual host names are available:
-
org.eclipse.orion.server.hosting.virtualHosts
The argument's value is a string with the form domains=domain-list
or IPs=ipList
, where domainList
is a comma-separated list of domains (which may include wildcards), and ipList
is a comma-separated list of IP addresses. The supplied values will be allocated to sites
so they, must be aliases for the Orion server.
Examples:
-
org.eclipse.orion.server.hosting.virtualHosts=IPs=127.0.0.2,127.0.0.3
- Makes 2 IPs available for allocation.
-
org.eclipse.orion.server.hosting.virtualHosts=domains=site.myorion.net
- Makes 1 domain available for allocation.
org.eclipse.orion.server.hosting.virtualHosts=domains=*.myorion.net
- Makes all of
*.myorion.net
available for allocation. Hosted sites will be given subdomains, for examplesite1.myorion.net
,site2.myorion.net
, etc.
-
org.eclipse.orion.server.hosting.virtualHosts=IPs=127.0.0.2,domains=*.myorion.net
- Equivalent to the previous example; when both domains and IPs are provided, domains are given priority.
Note about self-hosting
If you just want to try out hosting on your locally-running Orion server, and remote users will never need to access your hosted site, read this section.
It's usually sufficient to supply a list of 127.x.x.x addresses:
-
org.eclipse.orion.server.hosting.virtualHosts=ips=127.0.0.2,127.0.0.3,127.0.0.4
... and so on. On most platforms, any 127.x.x.x address is an alias for localhost. Mac OS X is a notable exception to this rule; OS X users must manually add an alias to any 127.x.x.x addresses they want to use for hosting, by running commands like this from a Terminal window:
-
sudo ifconfig lo0 alias 127.0.0.2 up
Windows users can create aliases using the [hosts file] if desired.
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, or missing required information.
- 404 Not Found when the site configuration id given in the request URI does not exist.
- 409 Conflict when a request indicates an action to 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 configurations, 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: application/json; charset=UTF-8 Content-Length: 307 { "HostingStatus" : { "Status" : "stopped" }, "Id" : "G", "Location" : "http://localhost:8080/site/G", "Mappings" : [ { "Source" : "/", "Target" : "/I" }, { "Source" : "/github", "Target" : "http://mamacdon.github.com" } ], "Name" : "MarkConfig", "Workspace" : "A" }
- 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 Content-Type: application/json; charset=UTF-8 Content-Length: 176 { "HostingStatus" : { "Status" : "stopped" }, "Id" : "d", "Location" : "http://localhost:8080/site/d", "Mappings" : [ ], "Name" : "My site configuration", "Workspace" : "A" }
- Detailed Explanation
- The Slug header contains the name of the site configuration to be created. If the Slug header is not present, there must instead be a Name field in the request body giving the name.
The request body must contain a Workspace field, whose value gives the nonnull, nonempty workspace id that the site configuration is associated to. Minimally, name and workspace are required to create a site configuration. Other fields may optionally be included; see #Site configuration for a full list.
If the optional request header X-Action: start is present, then the created site configuration is immediately started. The response body will reflect this in the HostingStatus field. (See also #Starting a 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; charset=UTF-8 Content-Length: 189 { "HostingStatus" : { "Status" : "stopped" }, "Id" : "d", "Location" : "http://localhost:8080/site/d", "Mappings" : [ ], "Name" : "New name for my site configuration", "Workspace" : "A" }
- Detailed Explanation
- The request body contains the fields of the site configuration that will be updated and their new values. If Name or Workspace fields appear in the request body, then their values must be nonnull and nonempty.
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
Content-Length: 0
- Detailed Explanation
- Successful deletion is indicated by a 200 OK response. Deleting a non-existent resource fails with a 404 Not Found response.
TODO: Should success be indicated by 204 No Content instead?
Other Actions
Starting a site configuration
- Overview
- To start a site configuration, send POST to the site configuration's location with appropriate X-Action request header.
- HTTP Method
- POST
- Example Request
POST /site/<siteConfigurationId>
X-Action: start
- Example Response
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 353 { "HostingStatus" : { "Status" : "started", "URL" : "http://127.0.0.102:8080" }, "Id" : "G", "Location" : "http://localhost:8080/site/G", "Mappings" : [ { "Source" : "/", "Target" : "/I" }, { "Source" : "/github", "Target" : "http://mamacdon.github.com" } ], "Name" : "MarkConfig", "Workspace" : "A" }
- Detailed Explanation
- Successful start of the site configuration is indicated by a 200 OK response. The response body gives the JSON representation of the site configuration (see #Site configuration), and will include a HostingStatus field.
Possible error responses include:
- 400 Bad Request — If the X-Action header is missing or invalid.
- 409 Conflict — If the site configuration is already started.
- 500 Internal Server Error — If the site couldn't be started because no virtual host name was available to assign to it. This usually indicates a problem with the server's hosting configuration that must be fixed by the server administrator.
Stopping a site configuration
- Overview
- To stop a site configuration, send POST to the site configuration's location with appropriate X-Action request header.
- HTTP Method
- POST
- Example Request
POST /site/<siteConfigurationId>
X-Action: stop
- Example Response
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 307 { "HostingStatus" : { "Status" : "stopped" }, "Id" : "G", "Location" : "http://localhost:8080/site/G", "Mappings" : [ { "Source" : "/", "Target" : "/I" }, { "Source" : "/github", "Target" : "http://mamacdon.github.com" } ], "Name" : "MarkConfig", "Workspace" : "A" }
- Detailed Explanation
- Successful stop of the site configuration is indicated by a 200 OK response. The response body gives the JSON representation of the site configuration (see #Site configuration).
Possible error responses include:
- 400 Bad Request — If the X-Action header is missing or invalid.
- 409 Conflict — If the site configuration is already stopped.
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 name of the site configuration. |
Workspace | string | The Id of the Workspace that the site configuration is associated to. |
Mappings | Array | Mappings defined by the site configuration. Each element of the array is a Mappings object (see #Mapping). |
HostHint | string | A hint used to determine what the hostname for the site configuration will be when launched. (Only relevant when a hosting subdomain has been configured on the server.) |
HostingStatus | object | Details about the hosting status of this site configuration. (See #Hosting Status.) |
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"
.
Hosting Status
If present, the HotingStatus object within the JSON representation of the site configuration may contain the following fields:
Field | Data type | Value |
---|---|---|
Status | string | started or stopped. |
URL | string | The URL where the hosted site can be accessed. (This field is only present when Status is started). |
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). |