Do's And Don'ts Of API Development

Witnessing the success of eBay, Amazon.com, and Salesforce.com through their use of APIs, many companies between 2001 and 2011 decided to publish their own APIs to attract outside developers to their businesses. What do developers think of such APIs in general?

"Hideously outdated documentation ... that will make you want to slit your wrists," said one developer, about the APIs he was working with.

"Authorization sucks," said another.

"At Facebook, everything is broken," said a third, not hesitating to name the source of his ire.

These were some of the comments from a survey conducted a few months ago by Your Trove, an online service for developers attempting to connect to social media APIs. The responses were frequently sprinkled with obscenities. Developers' biggest complaint is that API documentation is unreliable, is out of date, and offers poor guidance on how to implement a particular API. Developers also describe the error messages they're given when something goes wrong as too vague to help them figure out the cause of the problem.

The results of the survey were cited Tuesday by Seth Blank, founder of Your Trove, at the Business of APIs conference, meant to advance the art of constructing APIs for use by external developers. Speakers from Salesforce.com, Twitter, and LinkedIn said coming up with effective APIs for developers can mean launching the next expansion phase of your business; failing to do so often means missing a major opportunity.

[Want to learn how to do API documentation better than you're doing now? See Mashery: The E-Commerce Force Is With Them.]

The conference attracted a few hundred attendees to the Julia Morgan Ballroom of the old Merchants Exchange in San Francisco, a secondary venue to the enormous Moscone Center across town where Oracle OpenWorld is staged. The future of many businesses may lie as much with the focus of the little conference as with the big one.

Gartner predicts that 75% of the Fortune 1000 will offer a public API by 2014, but the Your Trove survey indicates many of them still have a long way to go before their APIs become a competitive factor.

Adam Trachtenberg, director of developer network at LinkedIn, said the online professional connection and social networking site added a hiring service through an easy-to-use API. Most users just post a professional profile on LinkedIn, but the widespread use of its APIs on different websites and online applications has made LinkedIn a common reference point.

LinkedIn now has 120 million users and its APIs have helped 30,000 developers establish connections to LinkedIn services. It now derives 48% of its revenue through its Post a Job service, charging $295 for a 30-day job posting, Trachtenberg said.

Ryan Sarver, Twitter's director of platform, said data analytics applied through social media APIs, such as Facebook, LinkedIn, or Twitter, "is a huge opportunity. Social Flow publishes aggregate content from an identifiable group, such as Forbes followers, to see what they're talking about." In doing so, it has been able to anticipate movements in the stock market ahead of Bloomberg business news feeds "by 15-16 minutes, which is huge in terms of market movements," giving followers of SocialFlow a chance to make their own trading decisions ahead of the market.

Netflix is a leading example of a company that transformed its business from the largest user of the U.S. Postal Service to one of the largest users of Amazon's EC2 cloud to deliver movies as a streaming service. It produced APIs that opened its catalog and ordering services to the iPhone, iPad, Xbox 360, Nintendo Wii, Sony Playstation, and other consumer devices. Its subscriber list expanded from 12 to 20 million in 2010 as it did so. Netflix's Daniel Jacobson, director of engineering, was a speaker at the conference.

Dave Carroll, director of developer evangelism for Salesforce.com, said his firm is growing--it crossed the $2 billion annual revenue run rate a few months ago--not only because it offers customer relationship management as an online service but also because it offers developers access to its CRM platform through public APIs. It didn't start out that way. In 2003, Salesforce.com came up with an API and charged $10,000 for a developer to access its documentation, viewing the API as a profit center. There were almost no takers, said Carroll.

The following year, it decided it was in its best interest to attract more developer activity and made the API free. That meant a Salesforce.com CRM user could set up links between his back office accounting or inventory systems and his data in the Salesforce.com database. That made the Salesforce.com applications much more useful to customers, Carroll said. Salesforce promptly set about expanding its API set.

In 2006, it launched an AppExchange, where developers could offer their Salesforce.com applications for sale. Each application in the AppExchange had been written to and depended on the Salesforce.com API. Many different functions were covered by the API, but at heart, it was a database API with such methods as Create, Update, Delete, and Query. The API methods mimicked those of the SQL data access language and broadened the use of Salesforce.com applications.

It now offers APIs to access its Chatter social networking service that work with its applications and RESTful APIs that work with various mobile devices. It also offers an API that customers may use to build applications that work on Force.com, its general purpose environment for customers who want to use it.

Giving outside developers access to your company's internal services broadens your business, if done in the right way. "Your API history ... reflects upon your business history and future evolution," warned Carroll.

He urged companies to keep their APIs simple and straightforward, with good documentation. Maintain backward compatibility. Otherwise, developers who used an early version will suddenly find their applications not working any longer and will need to engage in the time-consuming process of figuring out why.

"It all started with eBay and Amazon.com (creating public APIs as a way of supplying services over the Internet)," said Oren Michels, CEO of Mashery, an API management service and sponsor of the Business of APIs conference. "They each spent years and millions creating their API structures." Today, an enterprising company can absorb the lessons learned by the pioneers and create public APIs for much less.

Mashery is one of several firms, such as Apigee and Layer 7, that help enterprises establish and manage API use. Successful APIs, a complex combination of protocols and coded access to internal systems controlled by a registered developer key, can result in millions or billions of calls to those APIs a month as mobile applications bring new users to the company.