APIs are everywhere, but documentation is wanting

Private or internal APIs are far more common than the more well-known public ones. However, as developers move on to other projects and jobs, will others understand the intent and inner workings of all these APIs?

Photo: Stanford University Media Relations Department

These are some of the takeaways from Postman’s annual community survey of its developers, which finds that 80% of API activity is for private APIs, versus 20% spent on public APIs.

The survey also shows that microservices are front and center in API development. Microservices are the most interesting technology identified by the community for 2017. Twenty-seven perent consider microservices to be the most “exciting” technology initiative associated with API development and integration, followed by HTTP/2 (16%) and websockets (14%).

There is also a time commitment to APIs. The vast majority of developers spend 10 or more hours a week working with APIs.

One weak spot is API documentation — developers rated API documentation as below average, at a 2.3 mean on a scale from 0 to 5. There were many suggestions for improving documentation, with standardization (58%), better examples (55%) and sample code (50%) topping the suggestion list. Interestingly, software development kits (SDKs) were the lowest ranked result, at 17% — indicating that while developers use SDKs, they prefer good API documentation.

What is the direction API development needs to take these days, then? Kin Lane, API evangelist recently posted some thoughts on where one’s time and energy needs to be directed, pointing to “bots, voice and conversational APIs” as the next generation of API clients. “If you deliver data and content to your customers via your website and mobile applications, the chance that you will also be delivering it to conversational interfaces, and the bots and assistants emerging via Alexa and Google Home, as well as on Slack, Facebook, Twitter, and other messaging platforms, is increasing,” he states.

While Lane has doubts as to whether the home-based voice bots will live up to their current hype, he advises keeping an eye on how the multi-client interface market is evolving. In an age of computing just about anywhere and everywhere (even toothbrushes, ugh), developers need to be ready to go wherever their users go.

He leaves us with this additional thought:

“As a consumer, you won’t be able to avoid the conversational interfaces, and be required to engage with bots, and use voice enabled devices. This will push the need to have conversationally literate APIs that can deliver data to people in bite-size chunks. Sensors, cameras, drones, and other Internet-connected devices will increasingly be using APIs to do what they do, but voice, and other types of conversational interfaces will continue to evolve to become a common API client.”