Providing Web API

The challenge in designing an API is to provide flexibility but also hide the irrelevant information. Alex Bosworth provides a nice list of rules for providing a Web API with some examples.

What are a few simple rules for providing a web API?

  1. Keep it clean and simple
  2. Stick to standards
  3. Make it about data
  4. Keep it working
  5. Design for updates

Just mentioning them makes them so obvious. To an extent they very much apply to the non-Web APIs too, except probably the third point. Web is used mainly for information publishing and hence the APIs should deal wth data. A lot of APIs focus on providing the presentation or peripheral algorithms along with the data in the same package. While it might be convenient in some cases, it not only makes it inflexible, but also complicates the interface for the user, which violates the first rule – keep it clean and simple.

The fifth point indirectly stresses on maintaining the interface. If it changes, keep it versioned. Let the developer realise that the version number has changed and take an appropriate action. Changes to interface without intimation can go terribly wrong for the users. Not only should the newer interface try to not deviate a lot from the older one, but also consider the migration for the users.

I would like to just add another rule to the list:

Talk the user’s language.

Whether it is a Web API or not, talking the user’s language can help the user to understand and adopt the API faster. I have seen a lot of APIs asking users to know a lot of technical jargon when it is not exactly necessary. A rule of thumb to follow is to not introduce entities that the user does not already know about. This enables right encapsulation which in turn gives freedom to change internal algorithms or data structures without affecting the user. The right encapsulation also reduces information for the user which helps in keeping it simple.

Say your thought!

If you want to use HTML you can use these tags: <a>, <em>, <strong>, <abbr>, <code>, <blockquote>. Closing the tags will be appreciated as this site uses valid XHTML.



Abhijit Nadgouda
iface Consulting
+91 9819820312
My bookmarks


This is the weblog of Abhijit Nadgouda where he writes down his thoughts on software development and related topics. You are invited to subscribe to the feed to stay updated or check out more subscription options. Or you can choose to browse by one of the topics.