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 building a Web API, you’re likely going to need to figure out how to provide documentation to your end-users. If you didn’t think of that when you started your project, it can be a real deflating moment when it finally comes to mind. Documentation is boring and tedious. It’s nowhere near as fun as code.
Because documentation is boring, most software developers will quickly turn towards documentation tools. It’ll be so much faster to write documentation if we can just build or apply some software to do it, and building a software tool is much more fun than just sitting down and writing.
Documentation tools have advantages over hand-written documentation: they’re easier to keep up-to-date, they can produce output much faster, and they can provide much better coverage with less effort. But, before you go looking at API documentation tools, take a step back and figure out some high-level details about what your documentation looks like.
Cross-site request forgery (CSRF) is a type of security exploit where a user’s web browser is tricked by a third-party site into performing actions on websites that the user is logged into. It is often a difficult attack to pull off, as it requires a number of factors to line up at once. Protecting against it requires good discipline and good design practices, especially when it comes to protecting Web APIs.
Here’s a brief example of a fictitious CSRF attack against a bank:
Have you ever been stumped how to design a Web API? There are so many different approaches that you can take for even simple things, like paginating API result sets. If you list out your options, it can be easy to end up in analysis paralysis.
I like to remind myself that I’m not the first person to tread on this soil. I often take inspiration on design choices from well-known APIs, assuming that the hard work has already been done. But I realized lately that I’m not confident what a popular or successful API is, and that I have my own exposure biases in what is popular or successful. So, I decided to do some research to address that.
I defined an API’s success and popularity based upon whether it is supported by integration solutions. Integration solutions are systems which allow for the easier connecting or APIs together. I figure that if a service or API is popular, customers will demand it be available in integration systems that they use. As a result, the supported APIs could be correlated to determine the most popular APIs for integrating with.
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.