This would be funny if it wasn’t so pathetic and completely unnecessary.
In this, I see results of the “fail fast” mantra, superficial testing, the presumption that “I coded it, therefore it’s good,” and hostility to documentation as a badge of honor. These aren’t new software development problems, but the way they rapidly impact a large user base is a novel side-effect of present-day technology.
Marc Andressen famously claimed that “Software is Eating the World.” From the level of API quality that Google, Bing, and Twitter report, it looks like more has been bitten off than can be chewed.
What does it take to develop a robust and usable API? Technical tricks matter, but they can’t save a bad design. Design theory and general requirements for correctness were established a long time ago with Abstract Data Types and Meyer’s Design by Contract. Web APIs must also support a conversation between sender and receiver—a protocol. Getting the rules right for all possible conservations is a hard design problem. Security and performance flaws can be found and corrected, but not with happy path testing. Putting all this together takes a certain kind of artistry, much the same way that good music is more than just notes.
But even if you do all that, you’re not done, unless you don’t care about garnering users and growing usage. Code can’t tell the whole story. I learned this firsthand reading and critiquing thousands of pages of API documentation released through the Microsoft Open Specifications process. You have to explain how your API works so that any third party with basic programming skills can use it with minimal effort. I haven’t yet analyzed the buggy API complaints to see how many are about documentation, but it’s clear this is a common pain point.
So, releasing robust and usable APIs isn’t impossible, but it isn’t trivial. It takes thinking through and validating a design. It takes thorough testing of allowed and unallowed usage and data conditions. And it takes complete, consistent, and accurate documentation.
If all this seems like a lot, well, it is—especially when this kind of work isn’t your strong suit. That’s why we’re offering Advanced API Verification.