Connecting the dots…

RESTing

Working on a new project, I decided to start with getting the APIs in place first before even actually doing the front-end bit.  There were clearly some advantages to do that, one being that since I intend to build the entire application on the API, its a proof of concept in itself that you can build something useful using the API, unlike some websites where the websites have been provided as an additional layer that came in later and don’t fit in well or the consumer has a ridiculous amount of calls to get anything useful out of them.

Reading through the API design patterns, I found some principals that make a lot of sense and if they become part of the design mandate, they can result in robust and useful API’s and providing them can clearly result in newer products that API publishers couldn’t even have thought of themselves or didn’t have the time to build themselves

• GET or POST - Depends on what you are trying to do, the idea behind the REST interface is that it uses the four HTTP methods that can be applied to get a URI: GET, POST, PUT and DELETE.
  This goes very well with the actions that you want to perform using your API

  HTTP Method	CRUD Action	Description
  POST	CREATE	Create a new resource
  GET	RETRIEVE	Retrieve a representation of a resource
  PUT	UPDATE	Update a resource
  DELETE	DELETE	Delete a resource

  (taken from http://www.xml.com/lpt/a/2004/12/01/restful-web.html)

• Its only about data - One of the important things and the early mistakes that I used to make was putting presentation information with the data. Keeping the API in a presentation independent format allows developers to use their own imagination and build on top of them. Tieing them to a format restricts creativity.
• Multiple formats - Following up from the preview point, providing data in multiple formats esp cross platform formats is a very good idea. Common and popular formats include JSON (with all the AJAXY goodness), XML etc.
• Versioning - No API can remain the same as new features are added and exsisting functions are re-factored, but that shouldn’t mean the consumers should suffer due to the change, for all you know they might be basing they entire product on your API. Providing version information as part of the REST API url is one of the options.
  For e.g.: apis.xyz.com/1.0/getFriends and apis.xyz.com/1.2/getFriends

  This allows for the consumer to switch to the new API on their own after running regression tests or adapting to the new API to ensure availability of their application.

• Composite Functions - Anyone who has written apps on top of Flickr API or Twitter API is probably aware how painful it is sometimes when you need to get a bunch of information and they are not available together. Its useful to isolate functionality and have one call do exactly just one thing at time however it also means that the consumers would have to make as many calls to the API slowing down their applications and also negatively impacting your server performance. In such situtations its useful to provide additional apis which can bunch a couple of APIs and can provide the data in one go. For instance:I need to get a profile pic (profilepicture) and get the list of friends as well (friends), it would be useful to have another method available which gives me the entire profile in one go (profile) which I can decide to call depending on what level of granualirity of data I require.
• Naming Convention - This should usually be based on resource being represented, and usually should be a noun instead of a verb. So instead of /feed/getFriends it should be /feed/friends and then based on the kind of HTTP method data can be either be retrieved, created or updated.
• Status Codes - In addition to returning back representational data, you can also send back HTTP status codes which are very useful to AJAX based development where the developer can decide the next action without having to parse the response.
• Hackable Urls™ - Very useful to discovering apis and also makes them very easy to understand and learn. The best apis are the ones which dont require you to read through tons of documentation to figure out how to do complex things.
• Library Support - A very useful thing to provide along with API is a library to use the API, which contains calls that map to the API and abstract the user with the complexities of making http request and dealing with errors and connection failures. Another advantage of writing one is then you get to use it yourself and if released under the right licence you value from other people contributing to it as well. Additionally it allows you or others to port to other languages as well making your data available to more platforms that you could have made available yourself.

Additionally here’s an interesting introduction to rest

posting a quick note about the problem that I had after upgrading from Hardy Heron to ubuntu 8.10 with skype. There seemed to be a problem with the pulseaudio service and skype, everything worked fine with the audio i.e. playing and recording however using skype, i would get the error.”Problem with audio capture” and “Problem with audio playback”. It turns out that skype works fine with esound instead so running the following commands resolved the problem.

killall pulseaudio
sudo apt-get remove pulseaudio
sudo apt-get install esound
sudo rm /etc/X11/Xsession.d/70pulseaudio