User:SignpostMarv Martin/swslr/api: Difference between revisions

From Second Life Wiki
Jump to navigation Jump to search
initial notes
 
m →‎Exceptions: listify
 
(2 intermediate revisions by the same user not shown)
Line 10: Line 10:
=== Proposed URL Structure ===
=== Proposed URL Structure ===


http://{grid}.{world}.api.marvulous.com/{entity}/{property}/{uuid}[.{format}[?callback={callback}]]
<nowiki>http://</nowiki>{grid}.{world}.api.marvulous.com/{entity}/{property}/{uuid}[.{format}[?callback={callback}]]


All parameters MUST be expressed in lower-case.
All parameters MUST be expressed in lower-case.
Line 42: Line 42:


==== Entity Properties ====
==== Entity Properties ====
===== Ubiquitous properties =====
:''For a complete list of properties, see [[/entity properties]]''
These are properties that '''every''' entity has.


* key
In order to access the property of an entity, you need to construct the URL. Most properties are accessed in the form of {subdomain}/{entity}/{property}/{uuid of entity}
** Resident UUID
** Group UUID
** Region UUID
** Parcel UUID
** Event ID
* name
** Resident name
** Group name
** Region name
** Parcel name
** Event summary


===== Common properties =====
===== Examples =====
These are properties that '''most''' entities have.
Getting a Resident Rezday:


* description
agni.sl.api.marvulous.com/resident/rezday/83b3987f-9520-4275-8efe-3ac13dd3f635
** Resident profile text
** Group charter
** Parcel info text
** Event description
* image
** Resident profile texture
** Group insignia
** Region map tile
** Parcel listing texture
* rating
** Group: Mature, PG
** Region: Mature, PG
** Parcel: Mature, PG
** Event: Mature, PG


===== Shared properties =====
These are properties that have similar meaning for seperate entities, but aren't common or ubiquitous.


* owned parcels - Residents and Groups can both "own" land.
===== Exceptions =====
* co-ordinates - Regions have "global" co-ordinates, Parcels have "local" co-ordinates for their teleport location, Event co-ordinates usually use the co-ordinates of the parcel the event is held on.
name2key facilities ''may'' be offered- in this case, the following syntax would be used:
* category - Parcels and Events both have a category property.
* fee - Groups can have a membership fee, Events can have a cover charge; a L$ amount expressed as an [[integer]], with "0" being "free".


* agni.sl.api.marvulous.com/resident/key/signpostmarv martin
* agni.sl.api.marvulous.com/region/key/ahern
* agni.sl.api.marvulous.com/group/key/second life mentor


===== Special properties =====
name2key facilities cannot be offered on events or parcels due to their non-unique nature.
These are properties that only exist for individual entities.
 
====== Residents ======
* rezday - date Resident account was created
* picks
** mentioned picks - picks that mention a particular Resident's '''''full''''' name in the description text.
* founded groups
* owned regions
 
====== Groups ======
* founder - Groups have a Resident as a founder.
* member count - how many Residents are in the group.
* open enrollment - whether or not a Resident can join without an invite.
 
====== Regions ======
* owner - Regions have a Resident as an owner.
* parcels - Regions have at least 1 parcel, though this parcel does not have to be listed in search.
 
====== Parcels ======
* unique status - whether or not there's another parcel in the same region ''listed in search'' that has the same name.
* region - what region the Parcel is in
 
====== Events ======
* host    - the Resident who posted the event.
* dtstart - the date & time the event is scheduled to start
* dtend  - the date & time the event is scheduled to end
* region  - the name of the region the event is located in (regions that old events were held in may no longer exist, so presenting the UUID may either be pointless or impossible).
* parcel  - the name of the parcel the event will occur on (same "old events" issue that applies to regions applies to parcels)


== Output Formats ==
== Output Formats ==

Latest revision as of 15:46, 31 March 2009

It is starting to become obvious that a no-nonsense API is needed to access the Second Life data.

The swslr project marks data up using microformats, so geeky end-users would be free to use xpath queries without worrying about when I shuffle the HTML around a bit, or use a microformat-parsing webservice/library to do similar work.

However, not everyone can be fussed with doing things this way, or in the case of LSL, the necessary tools aren't available.

Feedback

Please leave feedback & questions on the talk page.

Proposed URL Structure

http://{grid}.{world}.api.marvulous.com/{entity}/{property}/{uuid}[.{format}[?callback={callback}]]

All parameters MUST be expressed in lower-case.

Sub-domain

Breaking this down, you have the "grid" (e.g. Agni, Teen, Deep Grid), then the "world" (Second Life or WoW) forming the sub-domain.

Note that World of Warcraft is only given as an example of another World type that could be supported, there are no concrete plans for implementation.
  • agni.sl.marvulous.com
  • teen.sl.marvulous.com
  • deep-grid.sl.marvulous.com
  • alonsus.wow.marvulous.com

Entity types

There are five entities in Second Life:

  1. Residents
  2. Groups
  3. Regions
  4. Parcels
  5. Events
  • agni.sl.marvulous.com/resident/
  • agni.sl.marvulous.com/group/
  • agni.sl.marvulous.com/region/
  • agni.sl.marvulous.com/parcel/
  • agni.sl.marvulous.com/event/

Entity Properties

For a complete list of properties, see /entity properties

In order to access the property of an entity, you need to construct the URL. Most properties are accessed in the form of {subdomain}/{entity}/{property}/{uuid of entity}

Examples

Getting a Resident Rezday:

agni.sl.api.marvulous.com/resident/rezday/83b3987f-9520-4275-8efe-3ac13dd3f635


Exceptions

name2key facilities may be offered- in this case, the following syntax would be used:

  • agni.sl.api.marvulous.com/resident/key/signpostmarv martin
  • agni.sl.api.marvulous.com/region/key/ahern
  • agni.sl.api.marvulous.com/group/key/second life mentor

name2key facilities cannot be offered on events or parcels due to their non-unique nature.

Output Formats

  • Plain text, served with a text/plain MIME type
  • JSON objects, served with an application/json MIME type
  • JSONP callbacks, served with a text/javascript MIME type
Retrieved from "https://wiki.secondlife.com/w/index.php?title=User:SignpostMarv_Martin/swslr/api&oldid=298932"