XPCA discovery model

[ferrisoxide]

XPCA Discovery Model
=========

Draft 0.1

Overview
--------

Clients of XPCA systems require some means to discover what resources
are available via an XPCA service. Because XPCA systens may be
constrained - both in terms of computational power and memory - the
representation of services must be simple and lightweight. The
discovery mechanism must also be extensible and able to represent
complex resources on devices with less severe constraints.

In line with the REST architectural model, XPCA's discovery mechanism
is based on the HATEOAS (Hypermedia as the Engine of Application
State) [1] constraint. Other than a general understanding of how
hypermedia-based resources work, clients require no in-depth knowledge
about how to connect to and make use of XPCA resources.

Using HATEOAS, XPCA systems become self-documenting. Knowing the end-
point of an XPCA service allows a client to interrogate it directly to
discover what resources are available. HATEOAS is also lightweight and
should be able to implemented on devices with constrained hardware.

A further benefit is that HATEOAS doesn't impose one single model for
resource representation. As long as the resources can be found via
hypermedia requests (e.g. HTTP GET) the HATEOAS architectural
constraint is satisfied. This fits with our long-standing goal of
providing "recipes" for implementing XPCA systems rather than
prescriptive designs.

Accessing the Resource Root
---------------------------

The XPCA end-point represents root-level access to a device (or group
of devices). In most systems the '/' URL will represent the end-point,
though '/xpca' is suggested as an alternative in environments where
the root URL already carries other meaning. In any case, the end-point
URL needs to be known by the client.

The XPCA root is retrieved by a simple HTTP GET command to the end-
point URL. The returned document will contain references to the XPCA
resources available - typically in HTML, XML or JSON but may be any
format supported by the XPCA client.

Simple XPCA Roots
-----------------

In its most basic form, an XPCA root represents a simple list of
available resources, e.g.

GET '/'

[returns]

{
"modbus_list_uri": "http://192.168.0.1/modbus",
"object_list_uri": "http://192.168.0.1/objects",
"history_list_uri: "http://192.168.0.1/history",
"about_uri": "http://192.168.0.1/about"
}

The same root can be represented as an HTML resource, e.g.

GET '/'

[returns]

...head/body/etc...

<a href="/modbus">modbus list</a>
<a href="/objects">object list</a>
<a href="/history">history list</a>
<a href="/about">about</a>

...

Microformat XPCA Roots
----------------------

While there is no specific requirement to represent XPCA resources as
anything other than hyperlinks, Microformats [2] offer a way to
structure and add metadata to XPCA resources without imposing a
significant overhead.

As an example, the XOXO [3] microformat provides a light-weight model
for representing resources as collections,

GET '/'

[returns]

...head/body/etc...
<ol class="xoxo">
<li><a href="/modbus">modbus list</a></li>
<li><a href="/objects">object list</a></li>
<li><a href="/history">history list</a></li>
<li><a href="/about">about</a></li>
</ol>
...

XOXO can also represent nested resources, providing a more detailed
map of an XPCA service via the root, e.g.

GET '/'

[returns]

...head/body/etc...
<ol class="xoxo">
<li>
<a href="/modbus">modbus list</a>
<ol class="xoxo">
<li><a href="/modbus/coils">modbus coils</a></li>
<li><a href="/modbus/registers">modbus registers</a></li>
</ol>
</li>
<li>
<a href="/objects">object list</a>
<ol class="xoxo">
<li><a href="/objects/heaters">heaters</a></li>
<li><a href="/objects/sensors">sensors</a></li>
</ol>
</li>
..
</ol>
...

The XPCA root should only present static resources (e.g. collection
resources). Any dynamic resource should be discoverable by further
interrogating the resources returned by the root.

Meta-data
---------

XOXO provides a metadata model based on <dl> (definition list tags)

GET '/'

[returns]

...head/body/etc...
<ol class="xoxo">
<li>
<a href="/modbus">modbus list</a>
<dl>
<dt>description</dt>
<dd>all modbus devices, addressable as /modbus/:device_id/</
dd>
</dl>
</li>
<li><a href="/objects">object list</a></li>
<ol class="xoxo">
<li>
<a href="/objects/heaters">heaters</a>
<ol class="xoxo">
<li>
<a href="/objects/heaters/1">boiler heater</a>
<dl>
<dt>name</dt>
<dd>Main boiler heater</dd>
</dl>
</li>
</ol>
</li>
</ol>
<li><a href="/history">history list</a></li>
<li><a href="/about">about</a></li>
</ol>
...

JSON Representations
--------------------

Kevin Marks, one of the initiators of the Microformats project,
provides a mapping between XOXO and JSON on his website [5]. Taking
cues from the model he presents, a mapping of a basic XOXO root would
appear like this:

GET '/' (JSON)

returns

[
{ "url" : "/modbus", "text" : "modbus list" },
{ "url" : "/objects", "text" : "object list" },
{ "url" : "/history", "text" : "history list" },
{ "url" : "/about", "text" : "about" }
]

A more complex representation, with meta data and nested resources,
might appear like this:

GET '/' (JSON)

returns

[
{ "url" : "/modbus", "text" : "modbus list",
"description" : "all modbus devices, addressable as /
modbus/:device_id/" },
{ "url" : "/objects", "text" : "object list", "collection" : [
{ "url" : "/objects/heaters", "text" : "heaters", "collection" :
[
{ "url" : "/objects/heaters/1", "text" : "boiler heater",
"name" : "Main boiler heater" } ]
}
]
}

...

]

N.b. this is fairly naive representation - there is possibly better
ways to represent collections.


Other Representations
---------------------

Earlier thinking about the XPCA discovery model centred around the
Atom Publishing Protocol [4] as the basis for representing all XPCA
resources. AtomPP's workspace/service model certainly lends it self to
representing the kinds of resources an XPCA system contains. In the
end it was discarded as the primary discovery model because of the
complexity it would impose on constrained devices.

However, there's no reason why XPCA end-points can't use the Atom
Publishing Protocol as an option. Using HATEOAS as the primary
discovery model, an XPCA root can return a link to an AtomPP interface
for further interrogation. In this way we allow XPCA systems to
implement complex and high-utility protocols where appropriate, while
"future proofing" them by enabling new protocols to be added over
time.

An interface to AtomPP in an XPCA root might look something like
this:

GET '/'

[returns]

...head/body/etc...
<a href="/atom-pp">Atom Publishing Protocol discovery interface</
a>
...


References
----------------

[1] http://en.wikipedia.org/wiki/HATEOAS
[2] http://en.wikipedia.org/wiki/Microformat
[3] http://microformats.org/wiki/xoxo
[4] http://en.wikipedia.org/wiki/Atom_Publishing_Protocol
[5] http://kevinmarks.com/cgi-bin/xoxotojson.py?url=http://kevinmarks.com

[flipback]

Good guide for future implementations! I will  translate it to Russian in near future)