hRESTS: Reaching for Descriptions of RESTful Services

Written by Jacek Kopecky Tuesday, 02 December 2024 08:50

RESTful services? You know, Flickr API, del.icio.us API , World Bank API, the Geonames service etc. These services are great sources of data and functionality for mashups and other applications. Let’s see how one uses such services.

Some of such services provide programming language libraries (see Flickr API kits) , e.g. in Javascript for running in the browser, but also in other languages, such as Ruby for running inside Railsapplications on the server. If such a library is available, you just download it and invoke its methods just like with any local APIs. If you use an IDE, it’ll help you with the method names and parameters etc.

Example (with a hypothetical API kit), which will add a picture to the user’s list of favorites:

flickr.favorites.add(user_auth, api_key, photo_id)

What if your programming language is not supported? What if there are no libraries at all for a service you want to use? Well it’s simple, you go, read the documentation, make those HTTP GET and POST requests using your favorite HTTP library, and all is nice and well. No help from the IDE because it doesn’t know about that Web service, it can only help you with the methods and parameters of the HTTP library.

Example without any Flickr API kit, with a hypothetical HTTP library:

URI = "http://api.flickr.com/services/rest/?method=flickr.favorites.add"
URI.append("&api_key=" + api_key)
URI.append("&photo_id=" + photo_id)
URI.append("&auth_token=" + auth_token) // retrieved previously
URI.append("&api_sig=" + computeFlickrApiSig(...)) // extra function specific for flickr
HTTP.POST(URI)

For the provider of a Web service, making the client libraries carries some nuisances: first, the effort to program and test it. Second, that’s multiplied by the number of programming languages one wants to support. Third, when the service evolves (and that’s not an “if”), the client libraries must be updated as well. Flickr, for instance, doesn’t maintain or provide support for the API kits it lists.

In contrast, WS-* services (those that use SOAP, WSDL and the like) don’t need client libraries because they have WSDL. A service description in WSDL makes it possible to have client libraries prepared dynamically or pre-generated in more languages than the providers care about.

Wouldn’t it be nice if RESTful services had something like WSDL descriptions?

Well, WSDL is generally perceived as unsuitable for RESTful services (but there are counterexamples). Then there’s WADL, with some support, but not much (yet?). Then there could be HTML forms (and XForms), which, for some reason, nobody seems to provide either.

Apart from HTTP, what’s common for all the RESTful services? (At least those we know of) There’s always pretty detailed documentation for developers. It contains all the information that’s necessary for invoking the service, but it’s in text, not in WADL/WSDL or any other machine-readable format.

Come hRESTS: it’s our microformat that identifies the operations and their inputs and outputs in the textual (HTML) documentation. A page with hRESTS markup can tell us, in a machine-readable way, what operations are available at a given RESTful API, at what URIs these operations are invoked (together with parameters, where necessary), with what HTTP method (GET, POST…), and it can also identify the blocks of documentation that describe the inputs and outputs of the operation.

Example (with a hypothetical hRESTS implementation in a dynamic language):

hrests.load("http://www.flickr.com/services/api/")
hrests.flickr.favorites.add(api_key, photo_id, auth_token, computeFlickrApiSig(...))

In hRESTS, we make it possible to describe the basic aspects of a service in a machine-readable way with very simple markup added to the already existing service documentation.

But we don’t stop here: we can extend hRESTS with further information, such as semantic annotations for Semantic Web Service automation. More about this in the future, though.

Btw, also see Tomas Vitvar’s take on hRESTS over at his blog. hRESTS is coauthored by myself,Karthik Gomadam and Tomas.