API World Conference reveals API developer pain points

When API developers and software architects from all over the world converged in San Francisco, they had a lot to say about the right and wrong ways to manage an API project.

Many enterprises are now starting to leverage APIs to cloud-enable their application architectures. 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. At the API World Conference and Expo Sept. 16 and 17 in San Francisco, developers and system architects explored some of the many pain points organizations run into in making their API useful to developers.

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.

An updated change log can provide developers a way to see how the API has evolved in order to correlate new problems with these changes. Providing developers with a road map for the evolution of the API can set developer expectations. Also, providing details about changes via release notes can help developers better understand how changes might affect their applications.

There are a variety of different channels to consider for communicating with developers, including blogs and participating in forums where developers hang out, like Stack Overflow. Musser also noted that while developers often complain about too much email, surveys have found that email is still the preferred mode of communication about changes to APIs. Email helps provide timely updates that will be noticed by developers using a particular API.

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.

Musser recommends that organizations provide developers with details about how the API works, a fast sign-up process and a 1-2-3 guide to getting started. It is also a good idea to make it easy for external developers to publish new applications in the enterprise’s API marketplace in order to increase the value developers get from using the API. It is also possible to reduce the friction for developers by providing free trials that allow them to kick the tires of the API before having to commit with a credit card.

The quick-start guide is an important part of the package. It should demonstrate all of the steps involved in implementing the most common use cases for the API. For example, Twilio shows developers how to use their own API for sending and receiving SMS and handling calls.

Not documenting APIs has costs, too

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. Other team members will end up reading the source code to understand it.When developers do write documentation, it is typically done once, and the documentation is not always updated. Documentation also seems to be the first thing that falls off when the development team is under stress. Enterprises with a significant API initiative might consider hiring a documentation team to work with developers, but this can get expensive. 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.

API development requires flexibility

Gareth Jones, API Architect for Microsoft OneNote, discussed some of the challenges and lessons around the evolution of the OneNote API. His team made a number of significant changes to the API over the last seven years and many of these involved difficult transitions. Jones shared his lessons at the API World Expo.

The OneNote team had a challenging discussion around not using XML, which led to almost religious debates on the topic. Eventually they shifted to a REST-based API and used JSON for the payload. It took some time to get the whole team on the same page and to commit to this approach. Jones said it is a good practice to decide upon the style of your API, and then to let the design flow through that.

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. The approach worked, but it was difficult to reference tables from HTML or from tokens in the text. Jones said it seemed like it would be difficult to explain how to do this to the external developers.

Eventually they settled on the MIME format, an older specification for adding attachments to email messages. 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. So the Microsoft team analyzed some of the code used to leverage the MIME format, and identified a few changes that allowed the API to work with slight variations.

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.”