Skip to main content

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.

Jump to: navigation, search

Difference between revisions of "Orion/Server API/Site Configuration API"

m (Note about hosting locally: More Mac OS X notes)
(Setting up hosting: Moved most of this section to Orion/Server admin guide)
Line 3: Line 3:
  
 
== Setting up hosting  ==
 
== Setting up hosting  ==
 
+
To use the [[#Starting_a_site_configuration|start]] and [[#Stopping_a_site_configuration|stop]] actions, the Orion server must be correctly configured for hosting. If you don't configure it yourself, it uses some default settings which will work if you're running the server locally under Windows or Linux (not Mac OS). For any other cases, you'll need to configure it yourself: see '''[[Orion/Server admin guide#Configuring virtual host names for launching sites | Server admin guide:Configuring virtual host names]]'''.
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. To do this, add a line to the <code>-vmargs</code> section of Orion's <code>eclipse.ini</code> file:
+
 
+
-Dorg.eclipse.orion.server.hosting.virtualHosts=value
+
 
+
The value is a comma-separated list, where each item in the list is either:
+
* A valid domain name (eg. <code>foo.myhost.net</code>), or
+
* A domain including wildcards (eg. <code>*.myhost.net</code>), or
+
* A valid IP address.
+
The values from the list will be allocated to hosted sites as virtual host names <!-- (in other words, values for the HTTP '''Host:''' header) -->, so they '''must''' be aliases for the Orion server. <!-- so that you can type the URL into your web browser and reach your hosted site. -->
+
 
+
''If you don't supply the argument when launching Orion, it uses a default setting that should allow you to [[#Note about hosting locally | host a locally-accessible site]] on most platforms (with the exception of OS X).''
+
 
+
=== Examples ===
+
;<code>-Dorg.eclipse.orion.server.hosting.virtualHosts=site.myhost.net</code>
+
:Makes 1 host name, <code>site.myhost.net</code>, available for allocation as a virtual host name.<p></p>
+
;<code>-Dorg.eclipse.orion.server.hosting.virtualHosts=127.0.0.2,127.0.0.3</code>
+
:Makes the 2 IP addresses available as virtual host names. Since they happen to be loopback addresses, any hosted site assigned to them will only be reachable from the local machine. (See the [[#Note_about_hosting locally|Note about hosting locally]]).<p></p>
+
;<code>-Dorg.eclipse.orion.server.hosting.virtualHosts=*.myhost.net</code>
+
:Makes all of <code>*.myhost.net</code> available for allocation. Hosted sites will be assigned to subdomains, for example <code>site1.myhost.net</code>, <code>site2.myhost.net</code>, etc.<p></p>
+
;<code>-Dorg.eclipse.orion.server.hosting.virtualHosts=foo.myhost.net,*.myhost.net</code>
+
:Makes 1 domain and 1 wildcard domain available. They will be allocated in the order provided. That is, <code>foo.myhost.net</code> will be assigned to the first hosted site that is launched, and subsequent launches will be assigned subdomains of <code>myhost.net</code>.
+
 
+
=== Note about hosting locally ===
+
 
+
In some cases, you may want to host a site on your locally-running Orion server, but remote users will never need to access it. To do this, it's usually sufficient to supply a list of loopback addresses in the launch argument:  
+
 
+
-Dorg.eclipse.orion.server.hosting.virtualHosts='''127.0.0.2,127.0.0.3'''
+
 
+
On most platforms, any 127.x.x.x address is an alias for localhost, so the above example would give you 2 IP addresses available for virtual hosts: 127.0.0.2 and 127.0.0.3.
+
 
+
If you don't supply the '''org.eclipse.orion.server.hosting.virtualHosts''' argument, Orion will use a default value. On Windows and Linux, the default assigns up to 16 addresses from the 127.0.0.2&ndash;127.0.0.254 range. On Mac OS X, there are no default addresses, so you will receive an error when you attempt to start a site.
+
 
+
{{Note|If you're using Mac OS X:| In OS X, only 127.0.0.1 resolves to localhost, so the above example will not work out-of-the-box. To make it work, first create the aliases by running these commands in Terminal.app:
+
 
+
$ sudo ifconfig lo0 alias 127.0.0.2 up
+
$ sudo ifconfig lo0 alias 127.0.0.3 up
+
 
+
Then try the example. Note that if you restart your machine, you'll have to do this again.
+
}}
+
 
+
If you prefer to use more readable hostnames instead of simple IP addresses, you can edit the [http://en.wikipedia.org/wiki/Hosts_file hosts file] on your local machine and create entries that map new hostnames to <code>127.0.0.1</code>. Then include those same hostnames in the launch argument, and Orion will use them:
+
 
+
-Dorg.eclipse.orion.server.hosting.virtualHosts='''myHostname1,myHostname2'''
+
 
+
<!-- By default, if you do not supply the '''<code>org.eclipse.orion.server.hosting.virtualHosts</code>''' argument, Orion will assume you are hosting locally, and make available the addresses from 127.0.0.2 &endash; 127.0.0.17. -->
+
  
 
== Status codes ==
 
== Status codes ==

Revision as of 15:48, 16 March 2011

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 use the start and stop actions, the Orion server must be correctly configured for hosting. If you don't configure it yourself, it uses some default settings which will work if you're running the server locally under Windows or Linux (not Mac OS). For any other cases, you'll need to configure it yourself: see Server admin guide:Configuring virtual host names.

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?


Start/Stop Actions

Warning2.png
This section will change in 0.2 M7.


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:


Hosting Status

If present, the HostingStatus 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).


See also

Copyright © Eclipse Foundation, Inc. All Rights Reserved.