REST

Revision as of 16:55, 9 October 2008

The following is taken from Alan M Webb's OpenSim REST Support Draft document dated 8/18/08. The information here and specification are works in progress but provide the basis for useful OpenSim integrations including content input and retrieval without direct DB access. --MoHax 00:10, 10 October 2008 (UTC)

There are a number of REST interfaces1 implemented within OpenSim. This document describes the work done to support specific interactions required in support of external application integration. XML is used to encode the payloads associated with these requests. The specific XML used is documented as an appendix, this is an interim specification.

What is REST?

The notion of Representational State Transfer (REST) was introduced by Roy Fielding in his doctoral dissertation in 2000. It is essentially an architectural concept rather than a protocol, and this has led to a variety of implementations, all of which might claim to be compliant REST implementations.

A REST interface is built upon the HTTP protocol, making use of the four principle methods defined therein: GET, PUT, POST, and DELETE. A fifth method HEAD is also supported, but that is really just a semantic variation of GET. The TRACE and OPTIONS methods have a less fundamental role. No other protocol is involved.

Note that REST does not specify the nature of the payload either sent or received. The interface associated with this document uses XML meta-data to manage an arbitrary payload. The need for a schema document to give form to this XML will be dealt with as a separate discussion.

Of particular significance is the understood meaning of the methods themselves, which is (and must be) as defined by the HTTP specification:

• GET retrieves the information identified by the associated URI and returns it to the requester. GET is idempotent. If the URI identifies a process, then it is the output of that process which is returned, and not the source text of that process. GET is conditional when the headers include any of the If headers. GET is partial if a range related header is included. The results of GET may be able to be cached.

• HEAD is functionally equivalent to GET except that the payload is not included in the response. The result of a HEAD request may be able to be cached.

• POST requests that the server accept the payload as a new entity, subordinate to the existing entity identified by the URI. POST places requirements upon session capabilities in the server insofar as it requires persistent connection and flow control capabilities.

• PUT indicates that the payload should be stored on the server under1 the resource named by the URI. If the named resource already exists, then the payload is considered to be a modified version of that resource. If the named resource does not exist, then it should be created by the server.

• DELETE requests that the server delete the resource identified by the URI.

Other methods (TRACE, OPTIONS, CONNECT) may be supported, but are not fundamental to the principles of REST. Use of these methods also implies specific requirements in terms of how the response codes should be used.

REST Inventory Support

The REST support in OpenSim is separated into a number of functional components, all of which live in the OpenSim/ApplicationPlugins/Rest hierarchy.

1. Plug-in management. E.g. RestPlugin.cs and Inventory/RestHandler.cs
2. Service management: Inventory/RestHandler.cs
3. REST implementation: RequestData.cs, Rest.cs
4. Service implementations: Inventory/RestInventoryServices.cs, Inventory/RestAssetServices.cs, etc.

This separation serves a number of purposes:

• it limits the sensitivity of each component to implementation changes in the others
• it simplifies the task of service implementation by “hiding” infrastructure
• it helps make services consistent by sharing a single implementation of REST related tasks

The design intention is that each subdirectory in the REST hierarchy, I.e. Inventory, corresponds to a distinct REST handler assembly consisting of service management and one or more service implementations. The Inventory directory is one example of such an assembly.

Configuration Parameters

In order for the REST handlers to be loaded and effective, statements must be added to the OpenSim.ini file. OpenSim reads the initialization file during start-up. This file is partitioned into various functional domains, e.g.

[Startup]
gridmode = false
physics = basicphysics

[RestPlugins]
enabled = false

[RestHandler]
enabled = false

The RestPlugins partition affects REST handlers in general and supports the following entries:

[RestPlugins]
enabled = true|false || false
god_key = <string> || “”
prefix  = <string>   || “/admin”

Only enabled=true is necessary to enable REST processing.

Additionally, REST inventory processing currently requires that the following partition be defined:

[RestHandler]
enabled = true|false || false
authenticate = true|false || true
extended-escape = true|false || true
realm = <string> || “OpenSim REST”
dump-asset = true|false || false
dump-line-size = int%8 || 32
path-fill = true|false || false

The partition name corresponds to the ConfigName value specified in the plug-in subclass, I.e. RestHandler.cs.

Again, only the enabled=true entry must be provided to enable the inventory handler; all other defaults are acceptable for normal operation. The meanings of these values will become apparent in the rest of the document.

When the server starts, the REST handler will publish several messages indicating which configuration values are in effect.

Effective URI

From a REST perspective, the path component of the URI is viewed as a resource identification, the precise significance of which depends upon the HTTP method being used. There are subtleties here, in some cases a prefix of the path may be viewed as a functional qualification of the authority, with the remainder of the URI being a resource identification within the domain of that authority. In this document, the notion of a service corresponds to the functional qualification mechanism just described.

The prefix value in the configuration file is used to construct the server's base prefix for REST services, as illustrated in the description of the inventory services prefix shown below:

http://<host>:<port>/admin/inventory
                     ^^^^^

In this URI /admin is the base prefix, and /inventory is a prefix extension that identifies the inventory service handler.

All requests that have an /admin/inventory prefix will be passed to the inventory handler. The prefix must be followed by the name of the avatar that owns the inventory in question. For example:

http://localhost:9000/admin/inventory/Alan Webb

Assuming the GET method, then this will return Alan Webb's inventory catalog, as XML data in the response payload, for example:

<Inventory>
<Folder name = “My Inventory” uuid=”11111111-...-111111111111” ....
        <Folder name=”Objects” uuid=....
        ....
        </Folder>
    </Folder>
</Inventory>

In this case /admin/inventory identiifes the service, and /Alan Webb is the resource specification component of the path.

Implementation Overview

The REST implementation being described is manifest in a subset of the files contained in the ApplicationPlugins/Rest file hierarchy. It is logically partitioned into three domains:

• Plugin and configuration management
• REST implementation services
• REST service providers

The objective here being to separate functionality so that the task of the service provider is made as straightforward as possible while ensuring that all services implemented using the interface are consistent in both approach and behavior.

Illustration 1: Overall Data Flow Model

As shown in Illustration 1: Overall Data Flow Model all requests originate, and are eventually returned to, the OpenSim HTTP server. The handler is isolated from this implementation by the IHttpAgentHandler interface and the OSHTTP data-types. After matching, the request is passed to the appropriate handler; this relationship is defined by the IRest interface and the RequestData data-type.

Changes to BaseHttpServer