We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
SceneAPI RESTful API Specification - FIWARE Forge Wiki

SceneAPI RESTful API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the Scene API

Please check the FI-WARE Open Specifications Legal Notice to understand the rights to use FI-WARE Open Specifications.

Interactive, multi-user Web applications such as virtual worlds often have the common requirements of storing the "world" or scene on a server, and communicating changes in it to participating clients. In some applications, such as external agents manipulating the scene infrequently, it is not necessary to use a real-time, live connection (for example WebSocket) for synchronizing the scene data, but instead providing a RESTful API for queries and modification gives the advantages of less continuous processing load on both the server and the client, and using a standard communication method instead of eg. a custom binary network protocol.

Scene API Core

The Scene API is a RESTful, resource-oriented API accessed via HTTP that uses XML-based representations for information interchange. It is used to query and manipulate the data contained in scene objects, as well as to manipulate the structure of the scene itself (creation and deletion of scene objects.) The scene data is organized according to Entity-Component-Attribute structure described in Scene and EC model: the individual scene objects are called entities, which contain components, which contain the actual data payload as attributes.

Intended Audience

This specification is intended for both software developers and reimplementers of this API. For the former, this document provides a full specification of using the supported operations. For the latter, this specification provides a full specification of how to implement those operations.

In order to use this specification, the reader should firstly have a general understanding of the Synchronization Generic Enabler, that implements this API.

API Change History

The Scene API version history is described in the table below:

Revision Date Changes Summary
Mar 14, 2014 * Initial version
Mar 30, 2016 * Added missing queries

How to Read This Document

All FI-WARE RESTful API specifications will follow the same list of conventions and will support certain common aspects. Please check Common aspects in FI-WARE Open Restful API Specifications.

For a description of some terms used along this document, see the Terns and Definitions.

Additional Resources

Here you can describe any other information or resources that you could need to understand this document. It could include also the link <url> in which to can obtain this specification and the link to obtain the schemas that we are using. E.g.

"You can download the most current version of this document from the FIWARE API specification website at <link to the url>. For more details about the <name of the GE service> that this API is based upon, please refer to <link to the High Level Description>. Related documents, including an Architectural Description, are available at the same site."

General Scene API Information

Resources Summary

The following diagram describes the resources that can be accessed with the Scene API, starting from the server base URL.

Representation Format

The Scene API supports data in XML format.

Resource Identification

All operations (GET, PUT, POST, DELETE) to the Scene API require the target resource to be identified. For HTTP transport, this is made using the mechanisms described by HTTP protocol specification as defined by IETF RFC-2616.

An operation with only the /entities identifier refers to the whole scene. This can be narrowed down first to an entity to be operated on by appending the entity's integer ID, for example /entities/123. Furthermore, it can be narrowed down to a specific component type, and finally to a specific attribute name, eg. /entities/123/placeable/transform.

Links and References

N/A.

Limits

N/A.

Versions

N/A.

Extensions

N/A.

Faults

Synchronous Faults

Fault Element Associated Error Codes Expected in All Requests?
notFound 404 The resource was not found for a query operation.
badRequest 400 The resource identifier was invalid for a modification operation, or XML data submitted in a POST operation was invalid.

When a fault happens, it is also transmitted in the reply body as text for convenience.

Asynchronous Faults

All current SceneAPI operations are synchronous in nature; therefore there are no asynchronous faults.

API Operations

Scene queries

Retrieve data of all entities

Verb URI Description
GET /entities Retrieve data of all scene entities

Normal Response Code(s): 200

Error Response Code(s): 404

Example response:

<scene>
 <entity temporary="false" id="1" sync="true">
  <component temporary="false" typeId="5" type="Script" sync="true">
   <attribute value="avatarmenu.js" type="AssetReferenceList" id="scriptRef" name="Script ref"/>
   <attribute value="true" type="bool" id="runOnLoad" name="Run on load"/>
   <attribute value="0" type="int" id="runMode" name="Run mode"/>
   <attribute value="" type="string" id="applicationName" name="Script application name"/>
   <attribute value="" type="string" id="className" name="Script class name"/>
  </component>
  <component temporary="false" typeId="26" type="Name" sync="true">
   <attribute value="AvatarMenu" type="string" id="name" name="Name"/>
   <attribute value="" type="string" id="description" name="Description"/>
   <attribute value="" type="string" id="group" name="Group"/>
  </component>
 </entity>
 <entity temporary="false" id="2" sync="true">
  <component temporary="false" typeId="5" type="Script" sync="true">
   <attribute value="avatarapplication.js;simpleavatar.js;exampleavataraddon.js" type="AssetReferenceList" id="scriptRef" name="Script ref"/>
   <attribute value="true" type="bool" id="runOnLoad" name="Run on load"/>
   <attribute value="0" type="int" id="runMode" name="Run mode"/>
   <attribute value="AvatarApp" type="string" id="applicationName" name="Script application name"/>
   <attribute value="" type="string" id="className" name="Script class name"/>
  </component>
  <component temporary="false" typeId="26" type="Name" sync="true">
   <attribute value="AvatarApp" type="string" id="name" name="Name"/>
   <attribute value="" type="string" id="description" name="Description"/>
   <attribute value="" type="string" id="group" name="Group"/>
  </component>
 </entity>
</scene>

Retrieve data of an entity

Verb URI Description
GET /entities/(entity-id) Retrieve data of a single scene entity

Normal Response Code(s): 200

Error Response Code(s): 404

Example response:

<entity temporary="false" id="1" sync="true">
 <component temporary="false" typeId="5" type="Script" sync="true">
  <attribute value="avatarmenu.js" type="AssetReferenceList" id="scriptRef" name="Script ref"/>
  <attribute value="true" type="bool" id="runOnLoad" name="Run on load"/>
  <attribute value="0" type="int" id="runMode" name="Run mode"/>
  <attribute value="" type="string" id="applicationName" name="Script application name"/>
  <attribute value="" type="string" id="className" name="Script class name"/>
 </component>
 <component temporary="false" typeId="26" type="Name" sync="true">
  <attribute value="AvatarMenu" type="string" id="name" name="Name"/>
  <attribute value="" type="string" id="description" name="Description"/>
  <attribute value="" type="string" id="group" name="Group"/>
 </component>
</entity>

Retrieve data of an entity by name

Verb URI Description
GET /entities?name=EntityName Retrieve data of a single scene entity by name

Normal Response Code(s): 200

Error Response Code(s): 404

Example response:

<entity temporary="false" id="1" sync="true">
 <component temporary="false" typeId="5" type="Script" sync="true">
  <attribute value="avatarmenu.js" type="AssetReferenceList" id="scriptRef" name="Script ref"/>
  <attribute value="true" type="bool" id="runOnLoad" name="Run on load"/>
  <attribute value="0" type="int" id="runMode" name="Run mode"/>
  <attribute value="" type="string" id="applicationName" name="Script application name"/>
  <attribute value="" type="string" id="className" name="Script class name"/>
 </component>
 <component temporary="false" typeId="26" type="Name" sync="true">
  <attribute value="AvatarMenu" type="string" id="name" name="Name"/>
  <attribute value="" type="string" id="description" name="Description"/>
  <attribute value="" type="string" id="group" name="Group"/>
 </component>
</entity>

Retrieve data of a component within an entity

Verb URI Description
GET /entities/(entity-id)/(component-type) Retrieve data of a single component within a scene entity

Normal Response Code(s): 200

Error Response Code(s): 404

Example response:

<component temporary="false" typeId="5" type="Script" sync="true">
 <attribute value="avatarmenu.js" type="AssetReferenceList" id="scriptRef" name="Script ref"/>
 <attribute value="true" type="bool" id="runOnLoad" name="Run on load"/>
 <attribute value="0" type="int" id="runMode" name="Run mode"/>
 <attribute value="" type="string" id="applicationName" name="Script application name"/>
 <attribute value="" type="string" id="className" name="Script class name"/>
</component>

Retrieve the value of an attribute within a component

Verb URI Description
GET /entities/(entity-id)/(component-type)/(attribute-name) Retrieve value of an attribute within a component

Normal Response Code(s): 200

Error Response Code(s): 404

The returned data is the attribute's value as text.

Creation of new scene objects

Create a new entity with a server-assigned ID

Verb URI Description
POST /entities Create a new entity into the scene, with server assigned ID.

Normal Response Code(s): 200

Error Response Code(s): 400

The POST request body may contain XML-serialized data to be put inside the entity (components & their attribute values). If omitted, an empty entity is created. The server will assign an entity ID to the new entity and return the entity's data as XML. An example response:

<entity temporary="false" id="1" sync="true"/>\n

Create a new entity with a specified ID

Verb URI Description
POST /entities/(entity-id) Create a new entity into the scene, with the specified ID.

Normal Response Code(s): 200

Error Response Code(s): 400

The POST request body may contain XML data to be put inside the entity (components & their attribute values). If omitted, an empty entity is created. The server will return the new entity's data as XML. If there is an ID conflict with an existing entity, the server will choose another ID. An example response:

<entity temporary="false" id="10" sync="true"/>\n

Create a new component into an entity

Verb URI Description
POST /entities/(entity-id)/(component-type) Create a new component into the scene entity.

Normal Response Code(s): 200

Error Response Code(s): 400

The POST request body may contain initial attribute values as XML to be put into the created component. If omitted, the attributes will have default values. The server will return the new component's data as XML. An example response of creating a component of type Placeable (scene node transformation) with default values:

<component temporary="false" typeId="20" type="Placeable" sync="true">
 <attribute value="0.000000,0.000000,0.000000,0.000000,0.000000,0.000000,1.000000,1.000000,1.000000" type="Transform" id="transform" name="Transform"/>
 <attribute value="false" type="bool" id="drawDebug" name="Show bounding box"/>
 <attribute value="true" type="bool" id="visible" name="Visible"/>
 <attribute value="1" type="int" id="selectionLayer" name="Selection layer"/>
 <attribute value="" type="EntityReference" id="parentRef" name="Parent entity ref"/>
 <attribute value="" type="string" id="parentBone" name="Parent bone name"/>
</component>

Modification of scene objects

Set new attribute value inside a component

Verb URI Description
PUT /entities/(entity-id)/(component-type)?(attribute-name)=(new-attribute-value) Set new value of an attribute inside a component.

Normal Response Code(s): 200

Error Response Code(s): 400

The server will return the component's new attribute values as XML.

Set new attribute values inside a component

Verb URI Description
PUT /entities/(entity-id)/(component-type) Set new attribute values inside a component.

Normal Response Code(s): 200

Error Response Code(s): 400

The attribute values are to be contained inside the PUT request body as XML. The server will return the component's new attribute values as XML.

Set entity's component data

Verb URI Description
PUT /entities/(entity-id) Set the scene entity's component data.

Normal Response Code(s): 200

Error Response Code(s): 400

Existing components in the entity will be deleted. The new component(s) and their attribute values are to be contained inside the PUT request body as XML. The server will return the entity's new data as XML.

Deletion of scene objects

Delete an entity

Verb URI Description
DELETE /entities/(entity-id) Delete an entity from the scene.

Normal Response Code(s): 200

Error Response Code(s): 400

Delete an entity by name

Verb URI Description
DELETE /entities?name=EntityName Delete an entity from the scene by name.

Normal Response Code(s): 200

Error Response Code(s): 400

Delete a component from an entity

Verb URI Description
DELETE /entities/(entity-id)/(component-type) Delete a component from the specified scene entity.

Normal Response Code(s): 200

Error Response Code(s): 400

Personal tools
Create a book