From 5ecfdd9bd2b16e11c232770cc07339e94b9457dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=BCnther=20Wagner?= Date: Wed, 2 Feb 2022 13:10:10 +0100 Subject: doc: add Bastian to AUTHORS and fix README (markdown now) --- AUTHORS | 1 + README | 76 --------------------------------------------------------------- README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 73 insertions(+), 76 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/AUTHORS b/AUTHORS index c309f7e..5ec6f6d 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,3 +1,4 @@ Rob Bradford Ross Burton Günther Wagner +Bastian Nocera diff --git a/README b/README deleted file mode 100644 index 2eb9e29..0000000 --- a/README +++ /dev/null @@ -1,76 +0,0 @@ -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]. - - -Nightly documentation: - -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. - -Demo application -~~~~~~~~~~~~~~~~~~~ - -A small Postman clone is provided in `examples/demo` to test the requests librest -is making. Flatpak is the recommended way of building and installing it: - -``` -# Add Flathub and the gnome-nightly repo -flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo -flatpak remote-add --user --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo - -# Install the gnome-nightly Sdk and Platform runtime -flatpak install --user gnome-nightly org.gnome.Sdk org.gnome.Platform -``` - -**Inside** the `examples/demo` folder run: -``` -flatpak-builder --user --install app org.gnome.Librest.json -``` -Run the application -``` -flatpak run org.gnome.RestDemo -``` - -[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/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..5ebea33 --- /dev/null +++ b/README.md @@ -0,0 +1,72 @@ +# 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]. + + +Nightly documentation: + +## 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. + +## Demo application + +A small Postman clone is provided in `examples/demo` to test the requests librest +is making. Flatpak is the recommended way of building and installing it: + +``` +# Add Flathub and the gnome-nightly repo +flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo +flatpak remote-add --user --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo + +# Install the gnome-nightly Sdk and Platform runtime +flatpak install --user gnome-nightly org.gnome.Sdk org.gnome.Platform +``` + +**Inside** the `examples/demo` folder run: +``` +flatpak-builder --user --install app org.gnome.Librest.json +``` +Run the application +``` +flatpak run org.gnome.RestDemo +``` + +[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/ -- cgit v1.2.1