librest
=======

This library has been designed to make it easier to access web services that
claim to be "RESTful". A reasonable definition of what this means can be found
on Wikipedia [1]. However a reasonable description is that a RESTful service
should have urls that represent remote objects which methods can then be
called on.

However it should be noted that the majority of services don't actually adhere
to this strict definition. Instead their RESTful end-point usually has an API
that is just simpler to use compared to other types of APIs they may support
(XML-RPC, for instance.). It is this kind of API that this library is
attempting to support.

It comprises of two parts: the first aims to make it easier to make requests
by providing a wrapper around libsoup [2], the second aids with XML parsing by
wrapping libxml2 [3].

Making requests
~~~~~~~~~~~~~~~

When a proxy is created for a url you are able to present a format string.
This format string is intended to represent the type of path for a remote
object, it is then possible to bind this format string with specific names of
objects to make this proxy concrete rather than abstract. We abstract the
parameters required for a particular call into it's own object which we can
then invoke both asynchronously and pseudo-asynchronously (by spinning the
main loop whilst waiting for an answer.) This has the advantage of allowing us
to support complex behaviour that depends on the parameters, for instance
signing a request: a requirement for many web services.

Handling the result
~~~~~~~~~~~~~~~~~~~

Standard XML parsers require a significant amount of work to parse a piece of
XML. In terms of a SAX parser this involves setting up the functions before
hand, in terms of a DOM parser this means dealing with complexity of a DOM
tree. The XML parsing components of librest are designed to try and behave a
bit like the BeautifulSoup parser [4]. It does this by parsing the XML into an
easily walkable tree were nodes have children for their descendents and
siblings for the nodes of the same type that share the same parent. This makes
it easy for instance to get a list of all the "photo" nodes in a document from
the root.

[1] - http://en.wikipedia.org/wiki/Representational_State_Transfer
[2] - http://live.gnome.org/LibSoup
[3] - http://xmlsoft.org/
[4] - http://www.crummy.com/software/BeautifulSoup/