Understanding cultural differences amongst developers (and between developers and the rest of the business) emerged as a key issue to address when designing APIs, according to a panel session on Creation, Design and Documentation of APIs at API Strategy and Practice in San Francisco today.

Evan Broder and Nelson Elhage from Stripe shared some of the common motivations that drive developers as they start to scale their API management, and together urged a more step-wise approach that may feel counterintuitive. "Solve the problem you have today, think about where to be tomorrow, and help those two feed off each other", said Broder and Elhage. It is a similar experience Kin Lane shared in his workshop on open government data on Wednesday. At that session, Lane described how he has to be "at both ends of the spectrum": explaining open data policy principles while also having working models of what an government open dataset accessible by API would look like. It is an emerging work trend where developers have to work both in the current environment, while also partly working in the future environment they are trying to create. Events like API Strategy and Practice (and sites like ProgrammableWeb, we hope!) become an essential resource to developers who need to learn how to straddle both timelines simultaneously.
The Stripe API is highly lauded amongst developers, many of whom consider it's documentation a 'game changer' in how API providers can appeal to developers. Industry observers have even noted that PayPal seemed to alter their API documentation to pick up some of best practice for their PayPal API. As Stripe has started scaling, they have separated out many of their API functions and, while acknowledging the need to move to a service oriented architecture, slowed themselves down to focus more on solving current problems while keeping an SOA endgame in sight. "[As we scale we have been] focusing at every point on solving a problem we had at the time, rather than a dictum that going forward everything has to be SOA."

"An API is the user interface to data," said Jakub Nesetril from Apiary.io. Like Broder and Elhage before him, Nesetril urged developers to overcome some of their impulses. In this case, Nesteril urges to fight against the human desire to jump straight into coding an API, to using a hackathon for API marketing, and the eventual desire to split contractual agreements from documentation. Nesetril suggests starting an API development process with wireframing and discovering a core group of early adopters who can help provide feedback on a mockup API. Regarding hackathons, Nesteril suggests API providers use the events to see how developers are using the API, rather than to market their API to the developer community. (It is an approach that AccountingSuite have used recently and were grateful for the practical feedback on how developers end up engaging with their early-release API.)

Following Nesteril, Jerome Louvel showed how using the APISpark product, developers could create an API quickly by focusing primarily on setting definitions and understanding the developer personas and potential uses cases that might emerge with an API. Here, developers and API designers were again urged to understand the actual human being who would be using the API in their work, not some amorphous generic population of end developers who will be impressed by your handiwork.

Finally, Kelsey Innis from Reverb! reminded the audience again of the basic human traits of all developers. While many may be highly proficient at communication with machines, perhaps communication with other humans (or with business sections of the enterprise) may not be their forte, and in a similar vein, communication between those working on backend processes may be speaking in different coding 'languages' that clientside developers. When creating APIs, Innis encouraged 'designing in' the sort of developer experience Pamela Fox had spoken of in the day's first keynote. "Remember, as developers, we will spend hours of time to get around doing something we don't want to do," Innis said practically, reminding the audience that developer motivations come down to laziness just like for almost everyone else on the planet. After all, developers are just human too. API Strategy and Practice continues today and through tomorrow at Parc55, San Francisco. Live streams of keynotes will be broadcast on ProgrammableWeb. You can also follow along with the discussion at the hashtag #apistrat.

About the author:Mark Boyd
is a ProgrammableWeb writer covering breaking news, API business strategies and models, open data, and smart cities.