B2D Strategies Part 3: Is Your API Documentation a Bug?

In this 4-part series looking at business-to-developer (B2D) strategies, we first looked at the emerging trend of 'API coming soon' landing pages. Then in Part 2 we gave some examples of successful private beta release phases of business APIs, aimed at building an engaged developer community around their API. In this third part, we speak with Jakub Nesetril (Apiary.io), Mehdi Medjaoui (Webshell.io) and Reza Shafii (MuleSoft) about why tools that engage with API consumer-developers are like Documentation for a new B2D-mindset. Understanding the wider context in which developers are creating and consuming APIs was crucial for Jakub Nesetril, Founder and CEO of API document creation service, Apiary. "The bottleneck is not CPU cycles anymore, it's the human cycles," Nesetril told ProgrammableWeb. "The amount of information and complexity is daunting. That's what is making developer engagement critical these days." Nesetril points to the changes in software development programming over the past ten years: "Now it is all about simplicity. The fact that 80% of APIs are developed in REST shows us that all of that development is a hunger for simplicity. Apiary brings this drive for simplicity to API development." Apiary is being utilized in many business' API releases, for example, the Wordtracker API discussed in Part 2 of our B2D series. It is proving to be a valuable way for provider-developers to test API code and provide a consistent and user-friendly documentation Framework. Apiary lets developers mock up a trial API, automatically generate code snippets for it, and test the prototype with early adopters (like the private beta testers mentioned in part 2 of our B2D series). Where the service is gaining most traction is its use by businesses to manage their API documentation and provide it in a consistent format on their Developer Portal. "We are absolutely floored by the amount of enthusiasm we have received from the developer community. It is very humbling and very exciting at the same time. We're excited by the amount of traction and sign up we have had in the past ten months," Nesetril said. This growing industry reputation has translated into seed funding of $1.63 million in early September and, by the end of that month, Apiary had signed on Akamai as a major partner. The enterprise cloud Platform Akamai routes up to a third of all internet traffic across its 130,000 global servers, and has launched the Open Developer platform, on which Apiary will provide API creation services. While clear and readily available API documentation is an important trust signal for many API-providing businesses, API creation and design tools are trying to reduce the need for it altogether. "Documentation is a bug," Mehdi Medjaoui - co-founder of Webshell - asserts, only slightly tongue-in-cheek. He points to the fact that if API developers are coding with an API and they need to leave their workflow to check API documentation on a developer portal, "Then that is a developer bug." Medjaoui is trying to be a little controversial with the statement, urging those service providers offering tools to API developers to rethink their mindset. "It should be like an autocomplete in a script editor. So for example, if I type in Facebook Graph API, it will show a list of the functions i can use with that API." It is a feature Medjaoui and his team are building into their Webshell service. Nesetril is already thinking along these lines for Apiary, at least in terms of providing in-service responses that reduce the need to interrupt the development workflow. "For example, developers can route errors through Apiary to show where the disconnect is. Before, this sort of thing would take days, now it can be solved in a couple of minutes with our self-help debugging tools," Nesetril said. Other services and tools are also addressing the documentation-as-bug mindset. APIhub's API Designer - that allows creation of APIs using the open source RAML specification - provides in-line suggestions as you code. "It is dynamic interpretation that is aiding you as you go in the design", Reza Shafii, Director of Product Management told ProgrammableWeb when we discussed the launch of the APIkit last week. The API Designer tool aims to provide API provider-developers with two realtime feedback loops: the first is this autocomplete-like interpretation that shows you only the functions that you can code with, and the second is a console interpretation that provides a "constant engagement with your user base". Shafii notes that with API Designer, provider-developers can be designing the API right in front of the API consumer-developer, who "can start playing around with it, it's definitely one of the feedback loops." Nesetril is also adamant that this is the future of B2D engagement: "One way we overcome the parity [between the different conceptual spaces between API providers and consumers] is to allow API providers to flesh out a prototype and engage discussion with early adopters [consumer-developers]. It creates a rapid iteration feedback loop, and avoids a huge amount of waste." Next, in the final part of the B2D series, we look at three models of developer experience and B2D engagement.


Disclosure: MuleSoft, which provides the APIhub service, is the parent company of ProgrammableWeb.

Be sure to read the next Tools article: 5 Reasons Your API Is Still Private