It’s the must-have of 2012: a RESTful API to allow developers to interact with your enterprise software without any messy overhead or complicated instructions. But while Web APIs are designed to be simple for programmers, designing and hosting your own APIs is no small challenge. A new O’Reilly book, “APIs: a Strategy Guide,” tackles this challenge.

Written by Greg Brail, Daniel Jacobson and Dan Woods, this new tome dives into the business benefits, necessities and best practices for building an API. Jacobson, who by day is director of engineering for the Netflix API, said that construction is more about who will use the API than who is building it.

“I think it starts with who you’re designing the API for,” said Jacobson. “One of the things we try to emphasize in the book is figuring out who the audience is for your API,” he said. “We want to design according to them. Is there a strong component of internal use? If you’re doing internal development and that’s your primary target, that’s very different than if you do a public API with unknown consumers.”

That’s a lesson learned at Netflix, where the internal streaming API has saved its developers thousands of hours of work. Instead of writing a streaming client for every platform from the PlayStation 3 to an Android mobile device, Netflix writes API interfaces for these devices. The result is that the presentation layer is unique on each device, but the underpinnings and fundamentals are essentially the same for any platform. No matter what device you use to watch Netflix, you can be assured it’s talking to the same API on the back end.

“The overwhelming consumption of the Netflix API is from our internal device teams; we can leverage this one distribution pipe to service the hundreds of devices,” said Jacobson. “The goal there is not to create a technical solution. We want to reach the audience and make them happy. If we want to be on a couple hundred devices, and have a Kindle application and an iPad application, the API is an enabling tool that helps us get there faster. We now have more than 800 devices supported.”

Because of this, said Jacobson, all of the developers who consume the Netflix API are in the same building. Making a change to the API requires a quick jaunt around the office to see if that change will ruin anyone’s life. Questions and problems can be resolved by walking down the hall.

But that’s not the case for every API, said Brail, who’s also CTO of Apigee. “An API is a contract with the developers, and the primary audience for your APIs are developers. It’s different if it’s enterprise software developers that use SOAP and .NET, or if it’s for Ruby-on-Rails folks. Those audiences are different, but in the end, the primary audience is developers,” he said.

But just having an API isn’t a ticket to Internet popularity for enterprises, said Brail. “When people think of APIs, they think, ‘We’ll put an API on the Web like Twitter did, and we’ll get rich!’ It doesn’t happen like that,” he said.

“In Netflix, they used this to solve an internal business problem. Internal use may be developers who are contractors, who are offshore, who may be dealing with two or three outside parties. That’s what an API is: It’s something designed for external consumption.”
#!
Don’t go changing
Perhaps the single most obvious and well-known best practice for APIs is around versioning. When developers are building on your API around the world without your knowledge, changing how that API behaves can have drastic consequences. Thus, Brail and Jacobson advocate versioning of APIs.

“Put a number one on it and don’t ever plan on changing it,” said Brail. “If your API version has more than one digit, you’re doing something wrong. It’s an interface version; you don’t change the interface. You try not to take them away. If you want to throw things over the wall and call it an API, you’ve got to be a little minimalist in what you expose.”

Thus, he advocates that developers host multiple versions of their API, which allows for applications built on version 1.0 to remain up and running for as long as your enterprise hosts version 1.0 of the API. Additions can be made to the API later, with developers triggering a specific version-number response by including that version number in their opening API calls.

Narinder Singh, cofounder of Appirio and CloudSpokes, said there are more hard-and-fast rules regarding APIs than just not changing them. CloudSpokes is a site where developers collect bounties on application requirements. Companies put up requests, typically along the lines of “use Google Maps’ API and our Salesforce application to make maps of deliveries.” Due to the nature of modern Web development, almost every CloudSpokes solution uses at least a few Web APIs.

With all those developers building with Web APIs, Singh has seen what it takes to make a successful API. “[Cloud VOIP service] Twilio has done a good job with their API,” he said. “How do I know? Because every time we run a contest on CloudSpokes that has requirements like ‘Pick two things and mash them up,’ Twilio shows up a disproportionate number of times, even when the use case doesn’t quite fit.”

For its Valentine’s Day contest, CloudSpokes asked developers to build applications that could get them a date. Three of the five final entries used Twilio. One of those applications, said Singh, automatically found potential suitors via dating sites, then connected the possible couple via VOIP using Twilio.

One of the things that makes Twilio’s API popular is the low barrier to entry presented to developers, said Singh. “It’s not just good enough to get to the end point of your API. You’ve got to get to where the developer first thinks, ‘I think I want to make something that connects to XYZ. How do I get a developer key? How do I get an account? Now how do I use the API?’ If you make it hard to get to that API, now I am already [annoyed] by the time I started using what you’ve made.”