Dan Fairs wrote an article on Web API design with a focus on efficiency issues for mobile devices. The article starts off with a very good and easy-to-follow description of what a REST API actually is, including examples of resources, representations, and interactions. He then presents some real-world practicalities, such as dealing with bad HTTP clients and returning rich error responses.
In terms of mobile devices, Dan notes that you want to minimize the number of necessary round trip API calls, which means including more information in a single response, i.e., introducing data redundancy or denormalization. Dan presents a technique that allows clients to specify how much redundant data is provided in a response based upon a parameter in the HTTP Accept header. This effectively allows different clients to tune their behavior and request the appropriate representation for the given application.
Google’s Alex Martelli gave a speech at PyCon 2011 focusing on API anti-patterns, which he defines as counterproductive behaviors that are often systematically repeated. He states that the worst anti-pattern is not having any API at all, and the second worst is not having any design (an accidental API). Most of the talk is aimed at a process or design level, though a couple of specific code examples are given. For example, Martelli talks about the fact that a lot of software is overdesigned, but when you’re dealing with an API it’s actually good to spend a lot of up-front time thinking about future expansion and evolution before release. In terms of designing a good API he suggests thinking about 3 ways to implement your API: the common concepts will be the core functionality that should be in your API. He also suggests that you should use your own API as much as possible. Finally, he spends some time talking about choosing to do something one way, not two ways, i.e., taking a stand and making a decision. The talk is just over 40 mins and offers some great high-level insights into how to go about designing a good API, be it C++, Python, or Web-based.
Rick Nucci wrote this article exposing 10 of the most common API pitfalls that he has encountered in Web services code (also known as Software as a Service, or Saas). His list includes problems such as exposing operations instead of objects, constantly changing the API on your users, not thinking about performance issues such as throttling services, and getting caught without a strategy for your API.
