Jump to: navigation, search

Difference between revisions of "Orion/Server API"

(Add link to site configuration API)
m (add categories)
Line 104: Line 104:
 
* Invoking a DELETE on the location will delete the resource
 
* Invoking a DELETE on the location will delete the resource
  
[[Category:Orion|Server API]]
+
[[Category:Orion/API]]
 +
[[Category:Orion/Server API]]

Revision as of 12:23, 11 March 2011

Server API 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.

Preference API

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

Git API

See Orion/Server API/Git API.

User API

See Orion/Server API/User API.

Site configuration API

See Orion/Server API/Site Configuration 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.

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
 }

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