Web API:
Everything on the Ogoglio platform can be accessed via the same web APIs, from the smallest thing to the largest space. 3D viewers use the APIs to initialize their model of spaces, the space hosting services use them to manage accounts and possessions, and the building tools use them to update spaces.
The web APIs follow the general guidelines of a RESTful system, as defined here: http://www.xfront.com/REST-Web-Services.html Broadly speaking, that means that each entity managed by an ogoglio space hosting service has a URL which can be queried with HTTP GETs and modified with POSTs, PUT, and DELETEs.
In addition to providing web APIs, the creators of the platform made every effort to choose protocols, languages, software, and formats using the following criteria (ordered by importance, most important first):
1. In common use by web developers
2. Human readable
3. In common use by 3D developers
4. Efficient for computation and transfer size
At present, the best way to understand the web APIs is to read the utility functions at the bottom of ogoglio.js. Those functions back the (ugly) Ajax UI that is in the default ogoglio web application.
Java coders can use the same api wrapper classes in use by the 3D viewer and the test suite. You will find those classes in the com.ogoglio.client package.
The XML is currently specified only by the classes in com.ogoglio.xml.
The web APIs are language neutral, with no data structures or syntax which are specific to the Java language.
URL Structure and example result XML:
TODO: make this legible
http://example.com/og/account/<username>/
<account email="susan@example.com" accountlevel="advanced" username="susan"/>
http://example.com/og/account/template/<comma seperated list of template IDs>/
<list>
<template ownerusername="library" templateid="1" displayname="Default Land"/>
<template ownerusername="library" templateid="2" displayname="Default Door"/>
</list>
http://example.com/og/account/<username>/template/
<list>
<template ownerusername="susan" templateid="7" displayname="Coffee Shop Building"/>
<template ownerusername="susan" templateid="8" displayname="Coffee Shop Canyon"/> </list>
http://example.com/og/account/<username>/template/<template ID>/
<template ownerusername="library" templateid="1" displayname="Default Land"/>
http://example.com/og/account/<username>/template/<template id>/geometry/data/<Level of Detail: 0, 1, or 2>
returns a wavefront Obj file if this template has a geometry for the LOD requested
http://example.com/og/account/<username>/template/<template id>/geometry/<obj resource name: Blah.mtl, texture.jpg>
returns the resource requested by the Obj or Mtl file, probably a mtl file or a jpeg/gif/png texture
http://example.com/og/account/<username>/template/<template id>/script
returns the javascript for this template
http://example.com/og/account/<username>/space/
<list>
<space ownerusername="library" simid="1" displayname="Angry Young Space" maxguests="20" spaceid="2" published="true"/>
<space ownerusername="library" simid="1" displayname="The Wharf" maxguests="0" spaceid="3" published="true"/>
</list>
http://example.com/og/account/<username>/membership/
<list>
<spacemember banned="false" spaceid="1" role="member" memberusername="library"/>
<spacemember banned="false" spaceid="2" role="builder" memberusername="library"/>
</list>
http://example.com/og/account/<username>/possession/
<list>
<possession ownerusername="library" templateid="5" possessionid="9"/> <possession ownerusername="library" templateid="3" possessionid="4" spaceid="2" thingid="2" />
</list>
http://example.com/og/account/<username>/possession/<possession id>
<possession ownerusername="library" templateid="3" possessionid="3" spaceid="2"/>
http://example.com/og/space/
<service usercount="0" simcount="1"/>
http://example.com/og/space/sim/
<list>
<sim displayname="Localhost Sim" simid="1" active="true" simuri="http://example.com/og/sim/"/>
</list>
http://example.com/og/space/<space id>
<space ownerusername="library" simid="1" displayname="Angry Young Space" maxguests="20" spaceid="2" published="true"/>
http://example.com/og/space/<space id>/door/
<list>
<door templateid="2" rz="0.0" ry="0.0" rx="0.0" rw="1.0" scalez="1.0" displayname="Solar System" scaley="1.0" templateowner="library" scalex="1.0" z="0.0" link="http://example.com/og/space/6/" y="0.0" x="-36.0" doorid="1"/>
</list>
http://example.com/og/space/<space id>/door/<door id>
<door templateid="2" rz="0.0" ry="0.0" rx="0.0" rw="1.0" scalez="1.0" displayname="Solar System" scaley="1.0" templateowner="library" scalex="1.0" z="0.0" link="http://example.com/og/space/6/" y="0.0" x="-36.0" doorid="1"/>
http://example.com/og/space/<space id>/member/
<list>
<spacemember banned="false" spaceid="5" role="member" memberusername="susan"/>
<spacemember banned="false" spaceid="5" role="member" memberusername="bob"/>
<spacemember banned="false" spaceid="5" role="member" memberusername="alice"/>
</list>
http://example.com/og/space/<space id>/member/<username>
<spacemember banned="false" spaceid="5" role="member" memberusername="susan"/>
http://example.com/og/space/<space id>/log/
returns text of log messages, one per line
http://example.com/og/space/<space id>/thing/
<list>
<thing templateid="1" rz="-0.0" ry="0" rx="-0.0" rw="1" scalez="1.0" displayname="Monkey" scaley="1.0" templateowner="library" scalex="1.0" possessionid="20" thingid="2" z="0.0" y="0.0" x="0.0" ownerusername="susan"/>
</list>
http://example.com/og/space/<space id>/thing/<thing id>
<thing templateid="1" rz="-0.0" ry="0" rx="-0.0" rw="1" scalez="1.0" displayname="Monkey" scaley="1.0" templateowner="library" scalex="1.0" possessionid="20" thingid="2" z="0.0" y="0.0" x="0.0" ownerusername="susan"/>
http://example.com/og/space/<space id>/thing/<thing id>/page/
<list>
<page rz="-0.0" ry="1.0" width="4.0" pageid="2" rx="0.0" rw="0.0" scalez="1.0" scaley="1.0" scalex="1.0" contenttype="text/plain" z="0.0" y="0.84" x="0.0" height="0.3"/>
<page rz="-0.0" ry="1.0" width="3.8" pageid="1" rx="0.0" rw="0.0" scalez="1.0" scaley="1.0" scalex="1.0" contenttype="image/jpeg" z="0.0" y="1.42" x="0.0" height="0.3"/>
</list>
http://example.com/og/space/<space id>/thing/<thing id>/page/<page id>
<page rz="-0.0" ry="1.0" width="4.0" pageid="2" rx="0.0" rw="0.0" scalez="1.0" scaley="1.0" scalex="1.0" contenttype="text/plain" z="0.0" y="0.84" x="0.0" height="0.3"/>
http://example.com/og/space/<space id>/thing/<thing id>/page/<page id>/content
returns the contents of the page: text, html, jpeg, gif, or png
http://example.com/og/space/<space id>/user/
<list>
<user rz="0.0" ry="0.0" rx="0.0" rw="1.0" scalez="1.0" username="library" scaley="1.0" scalex="1.0" z="0.0" y="0.0" x="0.0"/>
</list>
http://example.com/og/space/<space id>/user/<username>
<user rz="0.0" ry="0.0" rx="0.0" rw="1.0" scalez="1.0" username="library" scaley="1.0" scalex="1.0" z="0.0" y="0.0" x="0.0"/>
http://example.com/og/space/<space id>/setting/
<list>
<setting key="aSettingKey.1">Hello, Whirld</setting>
<setting key="anotherSettingKey_AAA">I am a rather large number.</setting>
</list>
http://example.com/og/space/<space id>/setting/<setting key>
returns the value of the setting or 404 if it is not set