Many of the API design opinions found on the web are academic discussions revolving around subjective interpretations of fuzzy standards as opposed to what makes sense in the real world. My goal with this post is to describe best practices for a pragmatic API designed for today’s web applications. I make no attempt to satisfy a standard if it doesn’t feel right. To help guide the decision making process, I’ve written down some requirements that the API must strive for…

Sooo much good advice in this article. Take this golden nugget, for example:

An API is a developer’s UI - just like any UI, it’s important to ensure the user’s experience is thought out carefully!

Yes! This reminds me of the conversation Mat Ryer and I had on Backstage a few weeks back about designing a Changelog API and how I might go about doing that.