HOW TO: Avoid Common Mistakes When Offering an API

The Web Development Series is supported by Rackspace, the better way to do hosting. Learn more about Rackspace’s hosting solutions here.

You don’t have to get hit by the proverbial bus to know it hurts, and you don’t have to make the same mistakes other devs have made on your way to a functional, widely used, efficiently managed API. In our final post on API management, our panel of experts has returned to give a few oft-committed mistakes for companies or developers offering an API for the first time — and how you can avoid them.

Clear & Fair Docs & Guidelines Are Key

Of course, offering an API involves a lot more than just creating the API itself. Guillaume Balas is an executive at 3scale, which offers full-featured API management and monetization tools. He says many of 3scale’s customers make mistakes such as not including documentation, sample code, or examples. He said that having no Terms and Conditions or unclear T&Cs is also unfortunately common.

Oren Michels is Mashery‘s CEO. His company does API management and strategy for more than 100 brands and 25,000 applications. He agrees that “lousy or inaccurate or missing documentation” is a common mistake, as is “terms and conditions that say ‘no commercial use’ or other things that suggest to developers that for some reason you get to make money and they don’t.”

And with your API, as with many other aspects of your business, “Keep It Simple, Stupid” is a dictum you can’t afford to forget. “Complex registration and key issuance protocols, or worse yet, requiring people to email a key request and wait for someone to get around to responding” is a practice Michels cautions you to avoid.

Be Prepared to Market Your Butt Off

Shanley Kane works on the product team at Apigee, a company that offers a range of API tools for developers and software companies. She says a common mistake is hiding your API under a bushel. “For companies new to the API game, opening up can be scary. Many companies make the mistake of not talking about their APIs — to press, developers and partners — and then wonder why no one is using their API. Commit to making your API a success by embracing the new rules of developer marketing.”

Augusto Marietti founded Mashape, a marketplace for building, distributing and hacking with APIs. He says the biggest mistake many API-offering companies make is not having enough focus in the marketing in the initial months after an API launch.

“You have to target not all kinds of developers,” he says, “but only the developers who need your API to solve a real problem they have. You have to look around, find and contact them, one by one. Those early adopters will spread your API to the world and thousands of other developers.”

Moreover, he notes that in addition to focus, you’ll need a good plan, a lot of resources and a certain amount of stamina. “Launching an API is like launching a new product, in that you have to give it all of your effort for at least six months. [You must] go to meetups, organize contests with interesting prizes that devs really want to have, evangelize your API around the world and organize hackathons.”

Marietti also recommends partnering with other companies with APIs related to your business. You’ll attract more business and split the cost of marketing your API.

Dimitri Sirota is an executive for Layer 7 Technologies, which offers its own suite of API management tools for the enterprise. He says another marketing (or PR) mistake is “having references that don’t relate to your business. Make sure you have references that look like you. For instance, if you are an enterprise, make sure you have enterprise customers supporting and referencing you.”

Get Feedback & Use It

Kane also cautions API-offerers to get feedback “early and often” to have a successful launch.

By “early and often,” she means getting select developers on-board and using your API in its most nascent stages. Invite a few trusted devs to use a private, “pre-alpha” version of your API, and put your API through a thorough beta stage, too.

While in these more formative stages, use the feedback you get to improve your design, find and squash bugs, and generally “make sure that the API is usable and pleasurable when you go live,” says Kane.

Brace Yourself for Traffic

Kane also says many API noobs are not prepared for the scope and scale of API traffic, which, she warns, is quite different from the traffic your web app might see.

“Your API will be accessed by mobile apps, web services and potentially hundreds of connected devices and platforms. Supporting that traffic means building out an API stack that will scale, prevent abuse and misuse, support mobile optimization and give you visibility and control.

“There are a number of API-specific solutions out there … but the most important thing is to understand how API traffic is different, and then you build your infrastructure accordingly.”

Sirota says many companies make the mistake of “not using a robust proxy that can provide a range of security and management controls.”

Understand How the API Will Affect Your — & Devs’ — Business

Michels gets the sage final word, saying that many companies make the mistake of not truly understanding how an API can grow their business. Instead, companies believe developers should all be paying for API access and should only get limited access, at that.

You might want to change directions, he says, if your API offers “no path to success — limits on traffic or usage that can’t be raised if someone is successful.” Or if your company is charging for your API, “believing that developers will plunk down a credit card and pay by the call, or by the thousands of calls.”

The overarching mistake here, he notes, is “not understanding how and why the API will improve and grow your business and focusing on making sure it does that.”

Sirota makes a similar point, saying a big mistake is “starting too big and worrying about revenue from the get-go. Start small. Get an API out there and learn — worry about revenue later.”

Do you have other tips for avoiding API mistakes? Let us know in the comments.

Series Supported by Rackspace


The Web Development Series is supported by Rackspace, the better way to do hosting. No more worrying about web hosting uptime. No more spending your time, energy and resources trying to stay on top of things like patching, updating, monitoring, backing up data and the like. Learn why.

Image based on a photo from iStockphoto user alxpin

More Dev & Design Resources from Mashable:

Ruby on Rails: Scaling Your App for Rapid Growth
Should Your API Be Free or Pay-to-Play?
HOW TO: Get Devs to Use Your Company’s API
Should Your Company Offer an API?
10 Tools for Getting Web Design Feedback

Image based on a photo from iStockphoto user alxpin.

More About: api, api management, api series, APIs, developers, web development series

For more Dev & Design coverage:

This entry was posted in api, api management, api series, APIs, developers, features, mashable, Web Development, web development series and tagged , , , , , , , , , . Bookmark the permalink.