A time-traveler is passing by 2013 and she opens a browser bookmark to
What HTTP status code does she get back from her response?
Well, it’s not going to be
200 OK, because it wasn’t OK with the server. The server couldn’t find the article that the client requested, because it won’t be published for another 43 years.
“Couldn’t find the article” sounds like a
404 Not Found status code. OK, very reasonable choice.
But, “The server couldn’t find the article” raises a bit of a doubt. A 404 is part of the 4xx-series status codes, which are all for client errors. Was this a client error, if it was the server’s fault for not finding the article? Shouldn’t she be getting
5xx Not Found?
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.