What are a few simple rules for providing a web API?
- Keep it clean and simple
- Stick to standards
- Make it about data
- Keep it working
- 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.