AssetServer/ClientDocs

From OpenSimulator

Revision as of 15:27, 2 December 2008 by Jhurliman (Talk | contribs)

Jump to: navigation, search

Contents

Client Documentation

Through the variety of extensions that ship with the asset server, several wire protocol formats are supported. Connectors for existing OpenSim grid protocols have been added wherever possible, along with new frontends that support web browsers and extensible metadata through JSON.

Reference Asset Protocol

To support the new metadata features and extensible content methods in the asset server, a new wire protocol is being designed. This is referred to in the documentation as the Reference Asset Protocol, and is currently using JSON as the transport format. JSON provides a lightweight markup and is loosely typed, allowing extended metadata to be transferred without breaking compatibility with existing or lightweight clients. Although the markup is pure JSON, some additional "types" are implemented by prefixing strings with type identifiers. This allows data to easily be mapped between OpenStructuredData and JSON. The types and their prefixes are as follows:

New JSON Types
uuid:: UUID, 128-bit unique identifier
uri:: Uniform resource identifier
date:: ISO-8601 numeric encoding in UTC
b64:: Base64-encoded binary data

Fetching Asset Metadata

Asset data may be located on the asset server, or scattered all over the world at various URLs. To find the location of the data for each asset, you must first fetch the asset metadata which can be retrieved at a fixed location. The URL for metadata is http://[someserver.com]/[assetid]/metadata. An example request:

GET /c228d1cf-4b5d-4ba8-84f4-899a0796aa97/metadata HTTP/1.1
Host: assets.virtualworld.com
Date: Mon, 22 Sep  2008 12:00:00 GMT
Authorization: OpenGrid ce9a6995-a737-4206-bae8-910cae310e94

The Authorization header is used to pass an authentication token (a login cookie) to the server. Because not all of the OpenSim protocols support authenticated asset retrieval yet, dummy authorization modules are used and the Authorization header is not currently needed.

An example response:

{
   "id":"uuid::c228d1cf-4b5d-4ba8-84f4-899a0796aa97",
   "name":"Default Avatar",
   "description":"",
   "creation_date":"date::2008-11-26T00:49:48.83Z",
   "type":"image/jp2",
   "sha1":"b64::3ftHyRoIfVYSeumfxRcSk4LZVVU=",
   "temporary":false,
   "methods":{
      "data":"uri::http://assets.virtualworld.com/c228d1cf-4b5d-4ba8-84f4-899a0796aa97/data"
   },
   "extra_data":{
      "components":3,
      "layer_ends":[
         580,
         1987,
         7983,
         31969,
         36041
      ]
   }
}

In this case the metadata is for a texture (type of "image/jp2", JPEG2000 compressed image). The methods map contains a single key/value pair for "data", the method used to fetch the actual asset data. The extra_data structure is also used in this example, to carry the number of components in the JPEG2000 data and the byte offsets of each quality layer in the texture.

Fetching Asset Data

Once the location of the asset data has been retrieved with a metadata request, a simple HTTP GET will download the content. The Authorization header is still required to fetch content that is not publicly accessible. In a future release, the asset server will support partial downloads with the standard HTTP Range header.

Creating an Asset

To create an asset, a simple JSON structure containing the asset metadata and data is POSTed to /createasset. Creating an asset and replacing an existing asset are done through the same interface. The "id" field in the POST data is optional. Specifying a UUID for the new asset may impose additional security restrictions, as this is generally reserved for system users who have been granted permission to replace existing assets. An example POST of a text file called note (specifying a UUID in the request) is shown here:

POST /createasset HTTP/1.1
Host: assets.virtualworld.com
Date: Mon, 22 Sep  2008 12:00:00 GMT
Authorization: OpenGrid ce9a6995-a737-4206-bae8-910cae310e94

Content-Type: application/json Content-Length: 225

{

  "id":"uuid::c228d1cf-4b5d-4ba8-84f4-899a0796aa97",
  "name":"note",
  "description":"A small note containing the word testing",
  "type":"text/plain",
  "temporary":false,
  "data":"b64::dGVzdGluZw=="

}</pre>

An HTTP status code 201 (Created) indicates success; all other status code indicate a failure to create the asset. On success, the return data will be a JSON map containing the key "id" with a value of the new asset's ID. If a failure occurred, the HTTP status description may contain more information. An example of a successful response:

JSON SUCCESS RESPONSE EXAMPLE

Content-Types

To maintain compatibility with existing interfaces such as OpenSim it is important that the correct content-type is used for uploads. Here is an example function that converts from known file extensions to common content-types. Note that all but three of the content-types (text/plain, application/xml, and application/octet-stream) can be converted to an OpenSim AssetType integer.

public static string ExtensionToContentType(string extension)
{
    switch (extension)
    {
        case "texture":
        case "jp2":
        case "j2c":
            return "image/jp2";
        case "sound":
        case "ogg":
            return "application/ogg";
        case "callingcard":
            return "application/x-metaverse-callingcard";
        case "landmark":
            return "application/x-metaverse-landmark";
        case "clothing":
            return "application/x-metaverse-clothing";
        case "primitive":
            return "application/x-metaverse-primitive";
        case "notecard":
            return "application/x-metaverse-notecard";
        case "lsl":
            return "application/x-metaverse-lsl";
        case "lso":
            return "application/x-metaverse-lso";
        case "tga":
            return "image/tga";
        case "bodypart":
            return "application/x-metaverse-bodypart";
        case "wav":
            return "audio/x-wav";
        case "jpg":
        case "jpeg":
            return "image/jpeg";
        case "animation":
            return "application/x-metaverse-animation";
        case "gesture":
            return "application/x-metaverse-gesture";
        case "simstate":
            return "application/x-metaverse-simstate";
        case "txt":
            return "text/plain";
        case "xml":
            return "application/xml";
        default:
            return "application/octet-stream";
    }
}

Reference Inventory Protocol

The inventory reference protocol is a work in progress. Leave notes on the discussion page for this document or start a thread on the opensim-dev mailing list if you'd like to be a part of the process.

OpenSim Asset Protocol

The OpenSim.Grid.AssetServer.exe protocol uses a REST interface for retrieving and storing assets. Assets are fetched with a GET to /assets/[assetid] or /assets/[assetid]?texture. The additional ?texture parameter is optional and does not change the response in any way. Asset data and metadata are returned in an XML format, with the asset data base64 encoded as an XML element. To upload, the same XML data structure that is received from a GET is POSTed to /assets/. The XML data is serialized from a class in OpenSim code, therefore the structure is subject to change. The current XML serialization is undocumented outside of source code.

OpenSim Inventory Protocol

OpenSim.Grid.InventoryServer.exe supports both a REST-like interface and an XML-RPC interface. Although the former interface shares some similar properties with a REST interface, it defines an additional messaging layer using HTTP POSTs of XML data for all requests. The REST-like interface is actually somewhere between SOAP and XML-RPC.

An example request, passing a single UUID argument in with session information:

<?xml version="1.0"?>
<RestSessionObjectOfGuid xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SessionID>070b4811-0a57-4fcd-bb3a-a03fbe9106d2</SessionID>
  <AvatarID>634ada51-3151-4e6d-a989-309f89f740e0</AvatarID>
  <Body>3207551c-da01-49ec-bb6e-f24f9ab36dcb</Body>
</RestSessionObjectOfGuid>

Another example, passing a single UUID argument with no session information:

<?xml version="1.0"?>
<guid>3207551c-da01-49ec-bb6e-f24f9ab36dcb</guid>

OpenID Authentication

The asset server currently has OpenID login support at http://[someserver.com]/authenticate. The process of obtaining authentication tokens and using them in requests will need to be explained more fully when authenticated requests are enabled.

Personal tools
General
About This Wiki