We have worked with many APIs here at Layer 7. And over time we’ve seen it all, ranging from the good to the bad. We even see the downright ugly. Now a good API is a beautiful thing; it encourages innovation, abstracts appropriately, and is designed with enough forethought that nobody needs to change it down the road. Resiliency is a good quality in an API. APIs are a little like cockroaches in that they will likely outlive the human race.
But what about the other ones? The ugly and bad ones? This is where developers could use some guidance.
Truth is, good API design isn’t really hard, but it’s not easy. One thing I point people to is Leonard Richardson’s Maturity Model for REST, which Martin Fowler explores in his blog. Now I’m not a REST purist by any means—truth is I’m as guilty of quick-and-dirty HTTP tunneling hacks as the next guy—but when you see the maturity phases laid out so succinctly, you can’t help but be inspired to move toward more “resourceful” thinking and maybe even learn to love HATEOS. Part of good API design is knowing what you should aspire to, and Richardson’s model is much more concise and accessible than Fielding’s thesis.
Another good source of advice is Joshua Bloch’s superb Google Tech Talk How to Design A Good API and Why it Matters. Bloch wrote what is arguably the most important book about Java ever written, and indeed his talk is about APIs using Java as the model. But don’t let that deter you; virtually everything Bloch discusses is as relevant to RESTful JSON-style APIs as it is to Java. Follow his advice, transpose it to you language of choice, and frame it with an understanding of where you want to land in the maturity model for REST, and you will end the day with great APIs.
K. Scott Morrison's Blog 