Enhance README with some documentation about librest.

1 files changed, 49 insertions, 0 deletions

diff --git a/README b/README
index e69de29..d73dc25 100644
--- a/README
+++ b/README
@@ -0,0 +1,49 @@
+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/