As I’ve been working part-time on developing a restful web service for a client and a service for Glaxal I thought it best to review RESTful Wev Services by Leonard Richardson and Sammy Ruby. I had previously read the RESTFUL web-service when it was originally written in 2007 and decided I needed a refresher of the concepts.
In my second reading I worried less about understanding the proper usage of http-methods like PUT or DELETE and focused more on specific structural gems buried in the text. A perfect example is a section discussing how to structure value-pair information such as geo-cordinates (Lat and Long). In a URI one could do /lat/34.2345/long/67.345/ problem with this structuring is it indicates that there is a hierarchical relationship between lat and long when there isn’t. They are in fact a value-pair. A better representation would be /geo-cords/34.2345,67.345/ One might wonder why I use a comma. I could of course use various other characters “+” or “;” that are acceptable and do not require encoding as defined by RFC-1738 URL. But the authors discuss that “,” should be used for ordinal sets of data and ; when the non-ordinal. So for instance if you wanted to represent the colors found in a bedroom that could be /bedroom/colors/brown;light-blue;white/
The authors also spend some time discussing the importance of creating and structuring what are known as ‘resources’. A resource can be anything including a composite of multiple resources. At one point the author makes the statement, if what you are trying to define isn’t working then perhaps you need another resource. A better solution than trying to bend and contort an API to work with your data.
Lastly, As I’m now in the process of writing several RESTful services there is a need to develop an approach for documenting and visualizing the service. Especially as my list of resources is growing and the need to organize everything into systems so I can a top-down approach. I’ve looked at the twitter api documentation which is a bottom-up perspective consisting of just a list of URLs which can be daunting to interpret. One of the author’s Leonard Riahcardson discusses the documenting format known as WADL which is supposed to be similar to the concept of the WSDL. However, much debate has erupted over the WADL format, for various reasons a few links: [Aristotle Pagaltzis, John
Heintz]. Some of the arguments are valid. I agree that having machine generated code breeds major issues and in some ways a RESTful service is self documenting. However, having a standard that provides a methodology for documenting is never a bad thing. Especially as I’m now in the process of creating a service with 20-30 resources each with various methods – some more RESTful than others. I don’t plan on building a WADL file and telling people that this is the be-all-document for everyone to use. But, having an internal documentation structure for myself would be beneficial as I’d conform to some set standard rather than creating my own.
