API World Conference reveals API developer pain points

This is not necessarily an easy task, and many enterprises end up creating problems for internal developers and outsiders who hope to leverage these services. ... A good starting point for determining how many problems the enterprise’s API is creating is to Google your company name with “API sucks,” said John Musser, CEO of API Science, an API analysis service provider. The results can characterize the magnitude and the specific nature of challenges developers are running into. Another warning sign is when a developer asks for a copy of your data, rather than using the API to access it. Poor developer communication equals poor APIs Poor communications skills create another pain point for making the API useful to developers, said Musser. This is primarily caused by not keeping developers informed or via infrequent communications. Developers will get annoyed when their application stops working for no apparent reason if the API is forked or changed without proper notification. … Documentation makes APIs developer friendly Another problem that Musser frequently encounters is that enterprises fail to make it easy for developers to use the API. They may fail to include a getting started guide, SDKs, code samples or tutorials. In other cases, it may be difficult to find a key for getting started. Sometimes an elaborate process is required to get the first project off the ground. … One of the key challenges that turned up at API World lies in poorly documented APIs. As API Science’s Musser pointed out, poor documentation can hinder adoption of an API by developers in creating new value with the API. But poor documentation can also cost an organization in lost developer productivity when the API will only be used internally, said Yves Vandewoude, co-founder and documentation evangelist at Qmino, a software development agency in Brussels.This is not always an easy problem to solve. Developers want to write code not documentation, said Vandewoude. At the same time, developers can get out of touch with their own API, and outside developers often need to look at the source code to understand the API. The original developer has the least to gain and the most to lose by spending a lot of time writing documentation. … Also these teams only tend to write documentation for the final product, which is not always useful during development.Another approach is to simply ignore documentation, and pray that developers will figure out how to use the API. Vandewoude said this approach tends to be more expensive in the long run in terms of lost developer productivity.A third approach lies in automatically generating documentation using a tool like Qmino’s MireDot application or the RAML API specification language. This documentation might not be as good as professional written documentation and may lack in-depth tutorials or samples. But it is always current. … Although JSON has a number of benefits, it also created challenges in many of the OneNote API use cases for saving Web pages. Jones said it is important to start from the perspective of how developers were likely to use the API and build around that. In the case of the OneNote API, the number one scenario was for sending a page of content into OneNote. So the team decided to leverage HTML as a front door for the API. ... While this approach worked well for experienced developers who made extensive use of libraries, other developers kept running into problems with the custom code written to process MIME messages. ... A good strategy lies in looking how developers are using the API, and then figuring out how to accommodate them. It can be challenging to experiment with different API implementation approaches. APIs are more difficult to test than Web applications in that it is not possible to do A/B testing on different API design approaches. “You cannot send out five samples of an API and expect people to program against all of them,” said Jones. “We were lucky to have internal customers. It might have been harder to tease good feedback from external developers.”