Neatly concealed in this tale about researching a financial API for inclusion in ProgrammableWeb’s API directory is some prescriptive advice for API providers who want to best optimize their developer experiences for maximum developer discoverability, explorability, and comprehension. Unlike a lot of the other prescriptive content we offer on ProgrammableWeb, this article doesn’t offer advice on what to do. But I think you’ll agree; after following our journey, you’ll have some idea of how to minimize the friction in your own developer messaging (as well as a bit more insight into how we do what we do here at ProgrammableWeb!).
Out of ProgrammableWeb’s three major functional areas — our article content, our research, and our directories (like the API and SDK directories) — we are best known for our directories. They drive over half of our overall traffic. I often describe our directories as the place where the two sides of the API community coin — the API providers and API consuming developers — congregate to find each other. Thousands of developers from around the world come to our directories every day to look for APIs to include in their next Web, desktop, mobile, or server app. Not coincidentally, in a fish-where-the-fish-are sort of way, ProgrammableWeb’s directories are widely acknowledged and promoted as one of the best places for API providers to list and improve the discoverability of their wares to developers. It’s a symbiotic relationship.
But running directories like the ones we run is more complicated than it looks; at least if you’re constantly optimizing to best serve the information needs of that community. Ideally, as suggested by projects like apis.json and the schema.org WebAPI schema, this can all be done by machine, requiring very little human intervention. If the entire API economy could agree to a common machine-readable schema and all API providers could publish something for each API that conforms to that schema, problem solved. Right?
Well, that’s a couple “ifs” right there and there are many more. This isn’t to say that standards can’t or won’t be useful. In fact, ProgrammableWeb will only get better as such standards take root because of how a goodly half of our battle lies in just finding the assets that should be listed in our directories.
But, the minute you dig into the real information needs of an end user looking to take advantage of such directories, you begin to discover all kinds of nuances and edge cases that are not only difficult to capture in such standards, but that can foil the sort of searches and queries the standards were meant to enable in the first place. Offering the best possible to outcomes to developers and API providers means that humans still have to keep close watch over the user interface and solve for great experiences. Do you remember the days when there was a relatively simple approach to informing a search engine like Google or Yahoo about your website? You just…