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"

(Exception Handling)
(Add page links for about and version API)
 
(36 intermediate revisions by 9 users not shown)
Line 1: Line 1:
= Server API Overview =
+
= Overview =
  
 
The Server API in Orion is not a single monolithic API. Rather Orion defines a series of distinct, standalone APIs for various kinds of tasks. A given server may implement one or more of these APIs, but not necessarily all of them.  
 
The Server API in Orion is not a single monolithic API. Rather Orion defines a series of distinct, standalone APIs for various kinds of tasks. A given server may implement one or more of these APIs, but not necessarily all of them.  
Line 10: Line 10:
 
* The default representation for request and response bodies is [http://www.json.org/ JSON], although a server may provide additional representations based on content type negotiation.
 
* The default representation for request and response bodies is [http://www.json.org/ JSON], although a server may provide additional representations based on content type negotiation.
  
= Preference API =
+
== Version header ==
 
+
See [[Orion/Server API/Preference API]].
+
 
+
= File API =
+
 
+
See [[Orion/Server API/File API]].
+
 
+
= Workspace API =
+
 
+
See [[Orion/Server API/Workspace API]].
+
 
+
= Import/Export API  =
+
 
+
See [[Orion/Server API/Transfer API]].
+
 
+
= Search API  =
+
 
+
=  General =
+
 
+
== Version Header ==
+
  
 
All server API requests must include the Orion-Version header. This allows the server to identify what protocol version is being used by the client, and produce appropriate responses for that version of client. This also allows a server to support other protocols for accessing the same resources (such as WebDAV). When the version header is absent, by default all modifying (PUT, POST) operations will fail. GET operations may return a reasonable default HTML response suitable for display in a browser.
 
All server API requests must include the Orion-Version header. This allows the server to identify what protocol version is being used by the client, and produce appropriate responses for that version of client. This also allows a server to support other protocols for accessing the same resources (such as WebDAV). When the version header is absent, by default all modifying (PUT, POST) operations will fail. GET operations may return a reasonable default HTML response suitable for display in a browser.
  
== Exception Handling ==
+
== Exception handling ==
  
 
When using the Orion Server API, errors are conveyed back to the client via a non-OK error code (4xx or 5xx). The response body contains a representation of a more detailed error status from the server.
 
When using the Orion Server API, errors are conveyed back to the client via a non-OK error code (4xx or 5xx). The response body contains a representation of a more detailed error status from the server.
Line 46: Line 26:
 
! Required
 
! Required
 
|-
 
|-
| httpCode
+
| HttpCode
 
| Integer HTTP response code
 
| Integer HTTP response code
 
| Yes
 
| Yes
 
|-
 
|-
| code
+
| Code
 
| Application specific integer response code
 
| Application specific integer response code
 
| No
 
| No
 
|-
 
|-
| severity
+
| Severity
| One of "error", "warning", "info", "cancel", or "ok"
+
| One of "Error", "Warning", "Info", "Cancel", or "Ok"
 
| Yes
 
| Yes
 
|-
 
|-
| message
+
| Message
 
| A high level error message
 
| A high level error message
 
| Yes
 
| Yes
 
|-
 
|-
| detailedMessage
+
| DetailedMessage
 
| Detailed error message
 
| Detailed error message
 
| No
 
| No
 
|-
 
|-
| cause
+
| Cause
 
| JSON object representation of another status that is the cause of this status (used for exception chaining)
 
| JSON object representation of another status that is the cause of this status (used for exception chaining)
 
| No
 
| No
 
|-
 
|-
| seeAlso
+
| SeeAlso
 
| URL of a page for more information on how to resolve the error
 
| URL of a page for more information on how to resolve the error
 
| No
 
| No
Line 76: Line 56:
  
 
Example:
 
Example:
 
+
<source lang="javascript">
   { "severity":"error",  
+
   { "Severity":"Error",  
     "code":0,  
+
     "Code":0,  
     "message":"This is the error message",  
+
     "Message":"This is the error message",  
     "detailedMessage":"This is the exception message",  
+
     "DetailedMessage":"This is the exception message",  
     "httpCode":500
+
     "HttpCode":500
 
   }
 
   }
 +
</source>
 +
== Progress reporting ==
 +
<span id="progress"></span>Long-running operations that cannot complete within a single request will instead return the location of a resource for tracking progress on that operation. The typical client work flow is:
 +
# Client sends request to start operation. The <tt>Location</tt> header in the response indicates the location of a progress resource. The response code is 202 Accepted, which helps the client distinguish long running operations from operations that complete within a single method invocation.
 +
# Client periodically checks state of progress resource. The response code will be 200 ok, but the Result (see below) will be undefined.
 +
# When long running task completes, progress resource includes a link to a resource representing the completed operation. Or maybe the Result is just what you want in the first place and the Location is somewhat related to something.
  
== Resource Locations ==
+
A progress resource has the following attributes:
<div id="location"></div>
+
 
All server API resources have a "Location" attribute. This attribute has the following properties:
+
{| border="1" cellspacing=0 style="text-align: center; width:90%"
 +
|- width="100%" align="center" style="background:#ccccff; padding: 0 5px 0 5px;" |
 +
! Property
 +
! Value
 +
! Required
 +
|-
 +
| Id
 +
| String identifier of the long running operation
 +
| Yes
 +
|-
 +
| Message
 +
| A message indicating the current operation state
 +
| Yes
 +
|-
 +
| Running
 +
| A boolean indicating whether the operation has completed
 +
| Yes
 +
|-
 +
| PercentComplete
 +
| An integer between 0 and 100 indicating what percentage of the operation has completed
 +
| Yes
 +
|-
 +
| Location
 +
| Once the operation has completed, this is the location of the operation result. While the operation is running this is the location of the progress resource itself. A client can keep getting this location until it becomes the result they are looking for.
 +
| No
 +
|-
 +
| Result
 +
| Once the operation has completed, this is a status object describing the operation result. Looks like Result.JsonData is what the original GET would have supplied if the task was not needed. While the operation is running, this property is undefined
 +
| No
 +
|}
 +
 
 +
== Resource locations ==
 +
<span id="location"></span>All server API resources have a "Location" attribute. This attribute has the following properties:
 
* When a resource is created, the POST operation that created it will return the location property both as an HTTP header, and in the response representation (attribute "Location" in JSON representations).
 
* When a resource is created, the POST operation that created it will return the location property both as an HTTP header, and in the response representation (attribute "Location" in JSON representations).
 
* Invoking GET on the resource location will return a representation of the resource.
 
* Invoking GET on the resource location will return a representation of the resource.
 
* Invoking PUT on the location will modify or replace the contents of the resource.
 
* Invoking PUT on the location will modify or replace the contents of the resource.
 
* Invoking a DELETE on the location will delete the resource
 
* Invoking a DELETE on the location will delete the resource
 +
 +
= Summary =
 +
 +
The following Orion server APIs are currently available:
 +
 +
{| border="1" cellspacing=0 style="text-align: center; width:90%"
 +
|- width="100%" align="center" style="background:#ccccff; padding: 0 5px 0 5px;" |
 +
! Name
 +
! Description
 +
! Link
 +
|-
 +
| Login API
 +
| API for logging into the Orion server
 +
| [http://wiki.eclipse.org/Orion/Server_API/Login_API Login API]
 +
|-
 +
| Preference API
 +
| API for accessing and storing trees of key/value preferences
 +
| [http://wiki.eclipse.org/Orion/Server_API/Preference_API Preference API]
 +
|-
 +
| File API
 +
| Used for accessing and modifying files and directories
 +
| [http://wiki.eclipse.org/Orion/Server_API/File_API File API]
 +
|-
 +
| Workspace API
 +
| API for creating and manipulating workspaces and projects
 +
| [http://wiki.eclipse.org/Orion/Server_API/Workspace_API Workspace API]
 +
|-
 +
| Import/Export API
 +
| Used for batch import/export of files and directories between an Orion workspace and a remote server or client
 +
| [http://wiki.eclipse.org/Orion/Server_API/Transfer_API Transfer API]
 +
|-
 +
| Git API
 +
| API for accessing and manipulating Git repositories
 +
| [http://wiki.eclipse.org/Orion/Server_API/Git_API Git API]
 +
|-
 +
| User API
 +
| Used for managing user accounts and manipulating individual user profiles
 +
| [http://wiki.eclipse.org/Orion/Server_API/User_API User API]
 +
|-
 +
| Site configuration API
 +
| API for launching and managing sites deployed from Orion workspaces.
 +
| [http://wiki.eclipse.org/Orion/Server_API/Site_Configuration_API Site Configuration API]
 +
|-
 +
| About API
 +
| API for inspecting / viewing general and component information about the running server.
 +
| [http://wiki.eclipse.org/Orion/Server_API/About_API Site About API]
 +
|-
 +
| Version API
 +
| API for viewing the version information about the running server.
 +
| [http://wiki.eclipse.org/Orion/Server_API/Version_API Site Version API]
 +
|}
 +
 +
[[Category:Orion]]

Latest revision as of 13:10, 13 March 2018

Overview

The Server API in Orion is not a single monolithic API. Rather Orion defines a series of distinct, standalone APIs for various kinds of tasks. A given server may implement one or more of these APIs, but not necessarily all of them.

All Orion server APIs have common design principles:

  • They are built on simple HTTP GET/PUT/POST/DELETE verbs with standard HTTP semantics.
  • GET operations are always non-destructive read-only operations
  • GET/PUT/DELETE are always idempotent, meaning the same operation can be safely repeated multiple times.
  • The relationship between resources is specified in links within response representations, rather than being inferred from the URI structure. For example a file's parent is specified by the Parent element in the response object, rather than by removing the last segment of the file's URI.
  • The default representation for request and response bodies is JSON, although a server may provide additional representations based on content type negotiation.

Version header

All server API requests must include the Orion-Version header. This allows the server to identify what protocol version is being used by the client, and produce appropriate responses for that version of client. This also allows a server to support other protocols for accessing the same resources (such as WebDAV). When the version header is absent, by default all modifying (PUT, POST) operations will fail. GET operations may return a reasonable default HTML response suitable for display in a browser.

Exception handling

When using the Orion Server API, errors are conveyed back to the client via a non-OK error code (4xx or 5xx). The response body contains a representation of a more detailed error status from the server.

Currently only a JSON representation is supported, with the following attributes:

Property Value Required
HttpCode Integer HTTP response code Yes
Code Application specific integer response code No
Severity One of "Error", "Warning", "Info", "Cancel", or "Ok" Yes
Message A high level error message Yes
DetailedMessage Detailed error message No
Cause JSON object representation of another status that is the cause of this status (used for exception chaining) No
SeeAlso URL of a page for more information on how to resolve the error No

Example:

  { "Severity":"Error", 
    "Code":0, 
    "Message":"This is the error message", 
    "DetailedMessage":"This is the exception message", 
    "HttpCode":500
  }

Progress reporting

Long-running operations that cannot complete within a single request will instead return the location of a resource for tracking progress on that operation. The typical client work flow is:

  1. Client sends request to start operation. The Location header in the response indicates the location of a progress resource. The response code is 202 Accepted, which helps the client distinguish long running operations from operations that complete within a single method invocation.
  2. Client periodically checks state of progress resource. The response code will be 200 ok, but the Result (see below) will be undefined.
  3. When long running task completes, progress resource includes a link to a resource representing the completed operation. Or maybe the Result is just what you want in the first place and the Location is somewhat related to something.

A progress resource has the following attributes:

Property Value Required
Id String identifier of the long running operation Yes
Message A message indicating the current operation state Yes
Running A boolean indicating whether the operation has completed Yes
PercentComplete An integer between 0 and 100 indicating what percentage of the operation has completed Yes
Location Once the operation has completed, this is the location of the operation result. While the operation is running this is the location of the progress resource itself. A client can keep getting this location until it becomes the result they are looking for. No
Result Once the operation has completed, this is a status object describing the operation result. Looks like Result.JsonData is what the original GET would have supplied if the task was not needed. While the operation is running, this property is undefined No

Resource locations

All server API resources have a "Location" attribute. This attribute has the following properties:

  • When a resource is created, the POST operation that created it will return the location property both as an HTTP header, and in the response representation (attribute "Location" in JSON representations).
  • Invoking GET on the resource location will return a representation of the resource.
  • Invoking PUT on the location will modify or replace the contents of the resource.
  • Invoking a DELETE on the location will delete the resource

Summary

The following Orion server APIs are currently available:

Name Description Link
Login API API for logging into the Orion server Login API
Preference API API for accessing and storing trees of key/value preferences Preference API
File API Used for accessing and modifying files and directories File API
Workspace API API for creating and manipulating workspaces and projects Workspace API
Import/Export API Used for batch import/export of files and directories between an Orion workspace and a remote server or client Transfer API
Git API API for accessing and manipulating Git repositories Git API
User API Used for managing user accounts and manipulating individual user profiles User API
Site configuration API API for launching and managing sites deployed from Orion workspaces. Site Configuration API
About API API for inspecting / viewing general and component information about the running server. Site About API
Version API API for viewing the version information about the running server. Site Version API

Back to the top