High-Level API Documentation Considerations
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...
[Read More]
Is your Web API susceptible to a CSRF exploit?
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:
[Read More]
2013 Most Popular and Successful Web APIs
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...
[Read More]
Idempotent Web APIs: What benefit do I get?
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.
[Read More]
Ain't Nobody Got Time For That: API Versioning
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.
[Read More]