API Management / Technology

Designing Compelling APIs

28 Apr 2014 10:19am, by

Developing an API for your company may seem like the challenge lies in the technical implementation, but in truth REST APIs are relatively simple to implement and release. The actual trick is in creating an API that brings value to your company, that developers want to use, and that is measurably successful.

An API needs to be treated as a first class product, from design through implementation. It needs goals, metrics, known use cases, and a compelling business story to tell. Imagine that you’re trapped with your CEO in an elevator and he asks why the API is important. You should be able to tell him clearly why the API is critical, at a business level, without resorting to the ever-popular “because everyone should have an API!” More APIs die unfortunate deaths because the development team can’t effectively articulate the value of their product to executives, even when those APIs are, in reality, quite successful.

An API is different than most other products that a company may offer. The difference is in the business values they provide.

APIs can bring value in multiple different ways:

  • Monetization. An API can bring money to the company directly, and this is the easiest business case to sell to your management. But truthfully, this only works well in cases where the API is the primary product of the company. Twilio and Sendgrid are two examples of successful companies who make money directly from their API. But for companies with a different primary product, this is not going to be a likely path to success.
  • User engagement. Do you want your users to engage with your system more frequently? From different devices? Do you want them to visit the site more frequently or add content more often? Do you want to make it easy for them to integrate information from your system into other product experiences? These are all valuable to the company. Offering specific users customized ways to interact with the system or presenting applications with a different focus can increase user’s loyalty to your product.
  • Visibility. Do you want your company to lead your industry? Making it easy for open source developers to interact with your system means that more people will be aware of your product and solidify your presence in the market.
  • Attracting new users. The more different ways a user can interact with your system, the more likely you’ll get their attention and engage them; and once they’ve engaged with your system you’re more likely to have devoted and loyal users.

Your product, the API, is going to be compared to the company’s other products when the R&D budget is determined, and the more compelling you can make the case for your API the better chance you’ll have of getting the resources you need to really make this product rock.

Now that you’ve decided the business goals for your API, it’s time to figure out how you want people to use the system. Use cases are critical here. They’ll help you make a useful API, write excellent tutorials, and avoid the pitfall of making a front-end API that looks like your back-end system but is useless to actual application developers.

It should be relatively easy to come up with three use cases: your website, a mobile application, and a simple integration with another system. Remember, the goal here is to think of the end user and what kinds of applications will be compelling to them when interacting with your product. Make these use cases strong enough that you understand how the flow will work, how people will use them, and what might excite them about your system. Feel free to highlight your product’s best features, or present things in a unique way — like providing an alternate browsing system to discover new products — that you think will keep bringing folks back.

When you’re done with this process you should be able to show these use cases to non-developers and have them understand fully how these applications can and will be used, and how they can contribute to the metrics you defined earlier.

Doing all this stuff up front is no fun, especially for developers who just want to jump in and write some code, but remember that the trick with an API isn’t in the technology you use or the formats you choose, but in making the right things easy. With those use cases in hand, you can start working on actually developing your API. Your primary goal here needs to be to make those use cases easy. When building a REST API, you can build a dogmatic REST API, but this is likely to be difficult for many of your clients to handle. A pragmatic REST design will tend to serve you better. Determine what kinds of calls a client is likely to make frequently and make that information easy to obtain. Sending basic information for a single call as the only option means that a developer is going to need to make multiple calls to build a single screen of information. For a mobile client this can be the kiss of death, as each call made by that mobile application is vulnerable to glitches in the network. Build your API with the end user in mind; make it easy to do the things you want developers to do, and your API will end up being much more successful.

This brings us to the final piece. You’ve developed your API, you’ve tested it against your known use cases, and you’re sure that it’s easy to do the things you want to encourage. How do you convince potential developers that your API can be trusted? Share as much of the information you’ve built with them as you can. If they know what you’re trying to achieve with your API, how you’re planning to measure it, and what use cases you’ve focused on, they’re going to have a lot more trust in the longevity of your API, and be much more likely to use it as the basis of their applications. Treat your developers as valued partners, not adversaries.

For further information on this type of approach, you can read “What Makes a Great API, the 5 Keys”, or purchase the e-book “A Practical Approach to API Design

Kirsten Hunter is an unapologetic hacker and passionate advocate for the development community. My technical interests range from graph databases to cloud services, and my experience supporting and evangelizing REST APIs has given me a unique perspective on developer success. In my copious free time I’m a gamer, fantasy reader, and all around rabble-rouser. My current day job is API Ninja at 3scale, an API management company committed to making sure everyone can create successful, compelling APIs.

Image by The Magic Tuba Pixie

A newsletter digest of the week’s most important stories & analyses.