A how-to guide for Web APIs

Article Tags

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.