When it comes to Web API best practices, idempotency is a pretty easy one to explain. An idempotent API operation is an operation that produces the same effect no matter how many times it is executed. Done, right? Now you know how to use that in your API design, how to explain it to your boss, and how to justify why it’s important. Right?
Well, probably not. That was a definition, not an explanation, and certainly not a justification.
Have you investigated how to make your API forward and backwards compatible, so that you can make changes to your API without affecting your current clients? Did you cry yourself to sleep shortly afterwards?
It’s really difficult to be confident about API compatibility because:
- You are planning for an unknown future.
- You are scared that you won’t be able to support unknown future changes.
- You are not omniscient.
- You are not a time-traveler.
- There are many convincing arguments about how to handle change in your API.
- All the convincing arguments conflict with each other.
My customers will be angry if I break my API.
When you release your Web API, it’s carved into stone. It’s a scary commitment to never make an incompatible change. If you fail, you’ll have irate customers yelling in your inbox, followed by your boss, and then your boss’s boss. You have to support this API. Forever. Unless you version it, right?
After publishing The Web API Checklist, I received comments (#1, #2) regarding API versioning. Before you struggle with how to version your API, I want you to know how to design your API to avoid future incompatibilities.
If my API is well designed, it won’t be fragile.
It is possible to design your API in a manner that reduces its fragility and increases its resilience to change. The key is to design your API around its intent. In the SOA world, this is also referred to as business-orientation. It’s a difficult design concept to understand, best explained with a fictitious example:
When you’re designing, testing, or releasing a new Web API, you’re building a new system on top of an existing complex and sophisticated system. At a minimum, you’re building upon HTTP, which is built upon TCP/IP, which is built upon a series of tubes. You’re also building upon a web server, an application framework, and maybe an API framework.
Most people, myself included, are not aware of all the intricacies and nuances of every component they’re building upon. Even if you deeply understand each component, it’s probably going to be too much information to hold in your head at one time.
“We know there are known knowns: there are things we know we know. We also know there are known unknowns: that is to say we know there are things we know we don’t know. But there are also unknown unknowns — the ones we don’t know we don’t know.” —Defense Secretary Donald Rumsfeld, Defense Department briefing, Feb 12, 2002
I don’t want you to build an API and only know about your unknown unknowns when they bite you in the ass. So, here’s a list of a bunch of things, both obvious and subtle, that can easily be missed when designing, testing, implementing, and releasing a Web API.