Skip to main content
Jump to: navigation, search

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

(JSON representations: links)
m (Deleting a site configuration)
 
(85 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{warning|Work in progress|This scenario has not been fully implemented yet. Progress is being tracked in [https://bugs.eclipse.org/bugs/show_bug.cgi?id=337212 bug 337212].}}
+
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 [http://en.wikipedia.org/wiki/Virtual_host virtual host] on an Orion server.
  
The Site Configuration API is a web server API for creating, editing, starting and stopping site configurations.
+
 
 +
== Setting up hosting  ==
 +
To successfully [[#Starting_a_site_configuration|start]] a site, 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]]'''.
  
 
== Status codes ==
 
== Status codes ==
The following HTTP response status codes are used by this API:
+
The following HTTP response status codes may be returned by this API:
* '''400 Bad Request''' when any of the request URI, request headers, or request body is malformed.
+
* '''200 OK''' for most requests that succeeded.
* '''404 Not Found''' when the site configuration Id given in the request URI does not exist.
+
* '''201 Created''' when a site configuration was created successfully.
* '''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.)
+
* '''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.
 +
* '''500 Internal Server Error''' when a request is made to start a site, but a problem with the server's hosting configuration prevented it from being started.
  
== CRUD Actions ==
+
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.
  
=== Getting all site configurations ===
+
== Actions ==
  
 +
=== Getting all site configurations ===
 
{{Orion/ServerAPI
 
{{Orion/ServerAPI
 
| method = GET
 
| method = GET
| overview = To retrieve the working tree status of a project, send a GET request to the git status location.
+
| overview = To retrieve all the logged-in-user's site configurations, send GET to the site config API.
 
| reqhead = /site
 
| reqhead = /site
 
| resphead = 200 OK
 
| resphead = 200 OK
  Content-Type: text/plain
+
Content-Type: application/json; charset=UTF-8
  Content-Length: 22
+
Content-Length: 333
 
| respbody =   
 
| respbody =   
  TBD
+
{
| explain = TBD.
+
    "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"
 +
        }
 +
    ]}
 +
| 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|Site configurations list]].
 
}}
 
}}
 
  
 
=== Getting a single site configuration ===
 
=== Getting a single site configuration ===
 
 
{{Orion/ServerAPI
 
{{Orion/ServerAPI
 
| method = GET
 
| method = GET
| overview = To retrieve changes between selected commits, commit and working tree, and so on. Send a GET request to the git diff location.
+
| overview = To retrieve a single site configuration, send GET to its location.
| reqhead = /site/siteConfigurationId
+
| reqhead = /site/{:site_id}
 
| resphead = 200 OK
 
| resphead = 200 OK
  Content-Type: text/plain
+
Content-Type: application/json; charset=UTF-8
  Content-Length: 22
+
Content-Length: 307
 
| respbody =   
 
| respbody =   
   TBD
+
{
| explain = TBD.
+
   "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"
 +
}
 +
| explain = On success, the response body contains the JSON representation of the site configuration. The representation is of type [[#Site configuration|Site configuration]].
 
}}
 
}}
  
=== Creating a site configuration ===
+
=== Creating a site configuration ===
  
 
{{Orion/ServerAPI
 
{{Orion/ServerAPI
| overview = Overview
+
| overview = To create a site configuration, send POST to the site configuration API.
 
| method = POST
 
| method = POST
| reqhead = /site HTTP/1.1
+
| reqhead = /site
Orion-Version: 1.0
+
  Slug: My site configuration
Content-Length: 48
+
Content-Type: application/json
+
  Slug: myfolder
+
 
| reqbody = {
 
| reqbody = {
   "Name" : "myfolder",
+
   "Workspace" : "A"
  "Directory" : "true"
+
 
  }
 
  }
| resphead = 201 OK
+
| resphead = 201 Created
| respbody = {
+
Content-Type: application/json; charset=UTF-8
  "Name" : "myfolder",
+
Content-Length: 176
"Location" : "http://example.com/file/MyProj/myfolder",
+
| respbody =  
"ETag" : "35fd43td3",
+
  {
"LocalTimeStamp" : "01234345009837",
+
  "HostingStatus" : {
"Directory" : "true"
+
    "Status" : "stopped"
"Attributes" : {
+
  },
"ReadOnly" : "false",
+
  "Id" : "d",
"Executable" : "true"
+
  "Location" : "http://localhost:8080/site/d",
 +
  "Mappings" : [ ],
 +
  "Name" : "My site configuration",
 +
  "Workspace" : "A"
 
  }
 
  }
}
+
| explain = 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.<p>The request body must contain a '''Workspace''' field, whose value gives the nonnull, nonempty [[Orion/Server API/Workspace API|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|Site configuration]] for a full list.</p><p>On success, the response body contains the representation of the site configuration that was created. The representation type is [[#Site configuration|Site configuration]].</p>
| explain = See [[EclipseWeb/Server_API/File_API#Notes_on_POST_method|Notes on POST method]] for further details.
+
 
}}
 
}}
  
 
=== Editing a site configuration ===
 
=== Editing a site configuration ===
 
 
{{Orion/ServerAPI
 
{{Orion/ServerAPI
| overview = The contents of an existing file can be replaced with a simple PUT to the file resource's [[#location|location]].
+
| overview = To update one or more fields of a site configuration, send PUT to the site configuration's location.
 
| method = PUT
 
| method = PUT
| reqhead = /file/MyProj/myfile.txt HTTP/1.1
+
| reqhead = /site/{:site_id}
Orion-Version: 1.0
+
If-Match: "35fd43td2"
+
Content-Type: text/plain
+
| reqbody = This is the new contents
+
| resphead = HTTP/1.1 200 OK
+
 
  Content-Type: application/json
 
  Content-Type: application/json
Content-Length: 132
+
| reqbody =
ETag: "35fd43td3"
+
  {
| respbody = {
+
  "Name": "New name for my site configuration"
  "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"
+
 
  }
 
  }
 +
| resphead = HTTP/1.1 200 OK
 +
Content-Type: application/json; charset=UTF-8
 +
Content-Length: 189
 +
| respbody =
 +
{
 +
  "HostingStatus" : {
 +
    "Status" : "stopped"
 +
  },
 +
  "Id" : "d",
 +
  "Location" : "http://localhost:8080/site/d",
 +
  "Mappings" : [ ],
 +
  "Name" : "New name for my site configuration",
 +
  "Workspace" : "A"
 
  }
 
  }
| explain = 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.
+
| explain = 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|Site configuration]].<p>For a detailed explanation of how to update the '''HostingStatus''' field, see the following two sections about [[#Starting a site configuration|starting]] and [[#Stopping a site configuration|stopping]].</p>
 
}}
 
}}
  
=== Deleting a site configuration ===
+
=== Starting a site configuration ===
 +
{{Orion/ServerAPI
 +
| overview = To start a site configuration, send PUT to the site configuration's location with a '''HostingStatus''' in the body that has its '''Status''' field set to "started".
 +
| method = PUT
 +
| reqhead = /site/{:site_id}
 +
| reqbody =
 +
{
 +
  "HostingStatus" : {
 +
    "Status" : "started",
 +
  }
 +
}
 +
| resphead = 200 OK
 +
Content-Type: application/json; charset=UTF-8
 +
Content-Length: 353
 +
| respbody =
 +
{
 +
  "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"
 +
}
 +
| explain = 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|Site configuration]]), and will include a '''URL''' field in the '''HostingStatus'''. The '''URL''' gives the web URL at which the running site can be accessed.<p>Possible error responses include:</p><ul><li>'''400 Bad Request''' &mdash; If a bogus value was provided in the '''Status''' field of the request.</li><li>'''500 Internal Server Error''' &mdash; 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 (see [[Orion/Server_admin_guide|Server admin guide]]).</ul>
 +
}}
  
 +
=== Stopping a site configuration ===
 
{{Orion/ServerAPI
 
{{Orion/ServerAPI
| overview = To delete a file or directory, send DELETE to the resource's [[#location|location]].
+
| overview = To stop a site configuration, send PUT to the site configuration's location, with a '''HostingStatus''' field in the request JSON that has its '''Status''' field set to "stopped".  
| method = DELETE
+
| method = PUT
| reqhead = /file/myfile.txt HTTP/1.1
+
| reqhead = /site/{:site_id}
  Orion-Version = 1.0
+
| reqbody =
  If-Match: 980sdfhsdf8f
+
{
| resphead = 204 OK
+
  "HostingStatus" : {
| explain = 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).
+
    "Status" : "stopped",
 +
  }
 +
  }
 +
| resphead = 200 OK
 +
Content-Type: application/json; charset=UTF-8
 +
  Content-Length: 307
 +
| respbody =  
 +
{
 +
  "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"
 +
}
 +
| explain = 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|Site configuration]]).<p>Possible error responses include:</p><ul><li>'''400 Bad Request''' &mdash; If a bogus value was provided in the '''Status''' field of the request.</li></ul>
 
}}
 
}}
  
 +
=== Deleting a site configuration ===
 +
{{Orion/ServerAPI
 +
| overview = To delete a site configuration, send DELETE to the site configuration's location.
 +
| method = DELETE
 +
| reqhead = /site/{:site_id}
 +
| resphead = 200 OK
 +
Content-Length: 0
  
== Other Actions ==
+
| explain = Successful deletion is indicated by a 200 OK response. Deleting a non-existent resource fails with a 404 Not Found response.<br><span style="background:#00FF00">'''TODO:''' Should success be indicated by 204 No Content instead?</span>
 +
}}
  
=== Starting a site configuration ===
+
= JSON representations  =
  
=== Stopping a site configuration ===
+
== Site configuration ==
 
+
{| cellspacing="0" border="1" style="text-align: center; width: 90%;"
= JSON representations =
+
|- align="center" style="background: none repeat scroll 0% 0% rgb(204, 204, 255); padding: 0pt 5px;"
 
+
! Field  
== Site configuration ==
+
! Data type  
{| border="1" cellspacing=0 style="text-align: center; width:90%"
+
|- width="100%" align="center" style="background:#ccccff; padding: 0 5px 0 5px;" |
+
! Field
+
! Data type
+
 
! Value
 
! Value
 
|-
 
|-
| Id
+
| Id  
| string
+
| string  
 
| Globally unique id of the site configuration.
 
| Globally unique id of the site configuration.
 
|-
 
|-
| Location
+
| Location  
| string
+
| string  
| The URL of this site configuration resource
+
| The URL of this site configuration resource.
 
|-
 
|-
| Name
+
| Name  
| string
+
| string  
| The URL where the started site configuration can be accessed.
+
| The name of the site configuration.
 
|-
 
|-
| Workspace
+
| Workspace  
| string
+
| string  
 
| The Id of the Workspace that the site configuration is associated to.
 
| The Id of the Workspace that the site configuration is associated to.
 
|-
 
|-
| Mappings
+
| Mappings  
| Array
+
| Array  
| The URL where the started site configuration can be accessed. Each element of the array is a Mappings object (see [[#Mapping]]).
+
| Mappings defined by the site configuration.<br>Each element of the array is a Mappings object (see [[#Mapping|Mapping]]).
 +
|-
 +
| HostHint
 +
| string
 +
| A hint used to determine what the hostname for the site configuration will be when launched.<br>(''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|Hosting Status]].)
 
|}
 
|}
  
== Mapping  ==
 
  
 +
== Mapping  ==
 
{| 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;"
Line 158: Line 261:
 
| Source  
 
| Source  
 
| string  
 
| 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.
+
| The source path.<br>Begins with a slash, and gives a request path on the running site configuration which will be mapped to the Target path.
 
|-
 
|-
 
| Target  
 
| Target  
 
| string  
 
| 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.
+
| The path to which requests matching the Source field will be mapped.<br>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:  
 
Examples of Source paths:  
 +
 
*<code>"/"</code> would map requests for the root of the site (/).  
 
*<code>"/"</code> would map requests for the root of the site (/).  
 
*<code>"/index.html"</code> would map requests for the index page (/index.html) of the site.
 
*<code>"/index.html"</code> would map requests for the index page (/index.html) of the site.
  
 +
<br> Examples of Target paths:
  
Examples of Target paths:
 
 
*<code>"/B/foo/bar"</code>, where '''B''' is the Id of a project.  
 
*<code>"/B/foo/bar"</code>, where '''B''' is the Id of a project.  
 
*<code>"http://o.aolcdn.com/dojo/1.5/dojo/dojo.xd.js"</code>.
 
*<code>"http://o.aolcdn.com/dojo/1.5/dojo/dojo.xd.js"</code>.
  
== List of site configurations ==
+
 
{| border="1" cellspacing=0 style="text-align: center; width:90%"
+
== Hosting Status  ==
|- width="100%" align="center" style="background:#ccccff; padding: 0 5px 0 5px;" |
+
If present, the HostingStatus object within the JSON representation of the site configuration may contain the following fields:
! Field
+
 
! Data type
+
{| 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;"
 +
! Field  
 +
! Data type  
 
! Value
 
! Value
 
|-
 
|-
| SiteConfigurations
+
| Status
| Array
+
| string
| The site configurations. Each element of the array is a site configuration object (see [[#Site configuration]]).
+
| '''started''' or '''stopped'''.
 +
|-
 +
| URL
 +
| string
 +
| The URL where the hosted site can be accessed.<br>''(This field is only present when Status is '''started''').''
 
|}
 
|}
  
== Hosting Status ==  
+
== Site configurations list ==
If present, the HotingStatus object within the JSON representation of the site configuration may support the following values:
+
{| 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;"
{| border="1" cellspacing=0 style="text-align: center; width:90%"
+
! Field  
|- width="100%" align="center" style="background:#ccccff; padding: 0 5px 0 5px;" |
+
! Data type  
! Field
+
! Data type
+
 
! Value
 
! Value
 
|-
 
|-
| Status
+
| SiteConfigurations
| string
+
| Array
| started | stopped
+
| The site configurations.<br>Each element of the array is a site configuration object (see [[#Site configuration|Site configuration]]).
|-
+
| URL
+
| string
+
| The URL where the started site configuration can be accessed.
+
 
|}
 
|}
 +
 +
 +
= See also =
 +
* [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;short_desc=sites;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;short_desc_type=allwordssubstr;component=Orion;product=e4 Open site-related bugs]
 +
 +
 +
[[Category:Orion/API|Sites]]
 +
[[Category:Orion/Server API|Sites]]

Latest revision as of 10:02, 25 May 2017

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 successfully start a site, 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 may be returned 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.
  • 500 Internal Server Error when a request is made to start a site, but a problem with the server's hosting configuration prevented it from being 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.

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/{:site_id}

  
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.

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/{:site_id}
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.

For a detailed explanation of how to update the HostingStatus field, see the following two sections about starting and stopping.


Starting a site configuration

Overview
To start a site configuration, send PUT to the site configuration's location with a HostingStatus in the body that has its Status field set to "started".
HTTP Method
PUT
Example Request
PUT /site/{:site_id}

{
  "HostingStatus" : {
    "Status" : "started",
  }
}  
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 URL field in the HostingStatus. The URL gives the web URL at which the running site can be accessed.

Possible error responses include:

  • 400 Bad Request — If a bogus value was provided in the Status field of the request.
  • 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 (see Server admin guide).


Stopping a site configuration

Overview
To stop a site configuration, send PUT to the site configuration's location, with a HostingStatus field in the request JSON that has its Status field set to "stopped".
HTTP Method
PUT
Example Request
PUT /site/{:site_id}

{
  "HostingStatus" : {
    "Status" : "stopped",
  }
}  
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 a bogus value was provided in the Status field of the request.


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/{:site_id}

  
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?


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

Back to the top