Make Your API as Popular as Pie

Everybody likes pie, right? There are many kinds of pie to choose from, you would think every pie would get eaten. Yet, every day many pies go uneaten, which is undeniably sad for the many who would want to eat that pie.

But this post is about APIs. Like pie, there are many different kinds. Also like pie, too many APIs go unconsumed. Just as a baker wants us to enjoy their pie, engineers and product managers should strive to have our APIs be devoured. More usage of your API should mean good things for the application it supports.

Whether you’re looking to have your API used internally or publicly, you can improve its chances by taking care in how you prepare and promote it. Follow these API design and documentation suggestions and your API will be tasty. Otherwise, you end up with an approach that is half-baked–and that’s no good for pie or APIs.

Your API Must Be Tasty

It is likely that when you think of a pie, you imagine a delicious crust and yummy filling. Yet, when thinking of APIs, many developers might recall negative experiences working with undocumented APIs or bloated data formats. Of course, you probably think the API you’re working on is just fine. For the developers who use it, fine may not be good enough.

“Edible" is a lousy end goal for a pie. You don’t want your pie to merely be fit for human consumption, and neither do you want your API to be only “workable."

Though not an exhaustive list, some of the best practices that you’ll want to include in your API design are to:

• Build on HTTP (actually, HTTPS–see below), using headers and status codes where possible to communicate in a way that machines can quickly interpret.
• Adopt RESTful practices where sensible, especially around naming resources as nouns and using HTTP verbs GET, PUT, POST, and DELETE appropriately.
• Provide data in JSON format, which is lightweight and easy to consume in most modern programming languages. A data format is not a great place to experiment because it provides another hurdle to developer adoption.
• Consider XML if your developers require it (for example, if you have C# or Java consumers, many of its tools expect XML).
• Bake events into your API with subscription webhooks (or REST hooks) so developers can receive the latest data without polling.
• Encourage or require developers to use encrypted connections via HTTPS, so that credentials are not passed in the clear.

The list above goes a long way toward making an appealing API, but it’s still just a list of features. They’re ingredients. You still need to put them together and help developers appreciate the finished dish.

---

A well-designed API on its own may not be enough, either. You'll also need to convince others to use it.

If you went to a pie shop known for its delicious crust, you are unlikely to see it described like this:

“Our crust contains flour, water, butter, sugar, and salt."

You’re much more likely to see the words “flaky" or “buttery." The same applies to your API's description and documentation. We’re not just talking about flowery speech here. It’s about helping developers know what your API can help them achieve rather than how it does it.

Take Clearbit’s home page, for example. It helps you understand what is possible with Clearbit before it gets into the details of how you can accomplish these tasks with its API. Companies where an API is a large part of its business, like Clearbit, Twilio, and SendGrid, are great examples to study. They look beyond the technical details of their APIs and focus on solutions.

You need the ingredients for a tasty API, but you also need to tell us how you’ve combined the ingredients to solve developer problems.

Know Your API Competition

You can’t possibly expect your API to solve developer problems if you don’t know how developers are trying to solve those problems today. Even pie has competition—and not just other pies. Sometimes you just want cookies.

The most common API competitor is someone trying to build the functionality of your app themselves. Perhaps there is an open source library that gets them close to your features. Or if your API supports a larger application, they may attempt to build the pieces they most need. Never underestimate a developer’s desire to build solutions themselves.

Sometimes the urge to build it themselves can show up in other ways. Perhaps it’s by scraping your site, which has many downsides related to data quality, user privacy, and system resources, among others. An even more common competitor to your API is manual effort. If your users copy and paste data from your app to another frequently, that’s some of the easiest competition to beat, because you’ll save them even more time—if you sell them on those savings.

There are even more potential competitors to internal APIs, including direct database access and duplicative (and inconsistent) business logic.

The reason to know your API competition is that it will help you understand what’s needed to convince developers that your API is a better solution. Understanding what end users are trying to do helps you start from real world use cases. When you’re solving actual problems, instead of imagined ones, you’ll increase the likelihood that a developer will be drawn to your API.

Assuming your API is now as tasty as pie, you may just need to demonstrate how to consume what you’ve made.

Help Them Dig In

Pie is typically served by the slice, on a plate, and with a utensil. An exception, as shown above, is a pie eating contest, where the pies must be eaten as quickly as possible without the help of hands.

When it comes to API documentation, the exception is the norm. Developers are typically thrown in as if they’re expected to inhale all the information at once. To provide a better experience, you’ll want to give them an easily-consumable portion and a utensil.

Your documentation should include more than simply an API reference. Some of the most important documents and tools accelerate the Time to First Hello World or TTFHW. They help bring more developers from exploring your API to actually using it. Your Hello World may not display “Hello World," as in the classic first program someone builds, but TTFHW does judge how long it takes developers to see basic results that they can modify and improve.

Getting Started Guides to Accelerate TTFHW

The most common way to get a developer on the right track is to provide a guide that walks through a simple scenario. These getting started materials give a high-level understanding of your API and the contexts where it might be used—and ideally help a user get their first Hello World from this one page.

GitHub unsurprisingly does a great job with their API documentation. Their getting started guide begins with simple, unauthenticated calls, with subsequent steps building on each other so you get a feel for what requests and responses look like.

Then, in the right-hand sidebar of that guide, there are even more guides waiting when the basics are covered.

SDKs or Other Libraries

We can argue over whether you call these wrappers, libraries, SDKs, or some other name, but the idea still matters. You definitely want some kind of code helpers for your API written in the languages that are most popular with your customers.

For example, identity management service StormPath does a fabulous job of meeting developers at their tech stack. Not only can you choose between almost a dozen languages, the company further breaks down its examples based on popular frameworks for your chosen language. And it provides sample code. All from its home page, by the way.

Common Use Cases

There are infinite possibilities within your API. But you need to tell developers about some of the more popular examples. Take, for example, Google’s Prediction API. Talk about a service that could do anything!

In its documentation, Google highlights three scenarios that you might use prediction: purchase prediction, spam detection, and sentiment analysis. Each is described briefly, with a seven-step tutorial for the last scenario.

Use cases for your API ground developers in specifics. Much like the Hello World, they help developers take the next step in customizing your solution to meet their needs.

Help TTFHW With Low Friction Deploys

It’s easier than ever to get code deployed on a cloud service now. You might as well make your example code cloud ready. Heroku Buttons and similar tools help developers separate the environment details from the code that actually uses your API.

For example, when the backend-as-a-service Parse announced its shutdown, it open sourced its Parse Server. Even better, it provided buttons that launch wizards to automatically clone the repository and deploy the service.

Why not do the same with your code examples? That’s what Twilio and others do with sample applications, tutorials, and more.

Share the Complete Vision

You want to sell me more than one slice of pie, right? You’ll want to make it clear the many different types of pie you serve and encourage me to come back when I’m hungry again. The TTFHW is just my first piece of pie in this metaphor. But if I never write another line of code afterwards, I’m not getting a complete view of what’s possible with your API.

While you want to make it easy to get started, there’s a lot that happens beyond that first Hello World. You don’t want to overwhelm developers with options, but if they go looking they should be able to find help with complete applications.

Offer Framework-specific Templates

Where SDKs get developers going in their favorite language, framework examples get even more specific with a developer’s workflow. Frameworks, such as Rails for Ruby, Flask for Python, or Angular for JavaScript, provide developers with ready-to-go, common functionality. When you integrate with a framework, you plug your API into that ecosystem.

A framework is about more than just TTFHW. It can decrease the time to first useful real app! That’s why Auth0 organizes its documentation home page around understanding the developer’s frame of reference, so it can recommend a framework. When you select from the four main choices, you’re then given multiple language frameworks that match that style of application.

Provide Full App Walkthroughs

Tutorials are great, but they don’t always cover a complete application. Much like frameworks can help developers get something useful, a step-by-step of a finished app can really help developers ship something comprehensive.

Twilio tutorials are a great example of walkthroughs in action. They start with common use cases and cover everything that’s needed to make it work. You can take the complete code and run it yourself, or look at each step separately, with the relevant code highlighted.

Publish Sample Apps to GitHub

Perhaps best paired with the other ideas in this section, publishing sample apps to GitHub makes it really easy for developers to get your code on their machine.

Rather than downloading or copy-pasting, developers can simply fork it to their own GitHub repository. Then, any changes they make are their own. And if there are issues to report, GitHub even has tools for that, as well.

Don’t Make Them Eat the Whole Pie

Some people want a big slice of pie and others just want a taste. When it comes to getting people interested in your API, the key is to have many different entry points available–let them choose their preferred slice of pie.

Getting started materials, sample applications, and tutorials are all excellent ways for developers to get started. But there are many ways to slice a pie. Here are some less technical approaches you might consider:

• Aim some materials at amateur developers: APIs are becoming more commonplace, which means those trying to consume your API have varying levels of technical background. Consider introductory tutorials that start from the very basics, or provide tools to help limit or eliminate the code they have to write.
• Encourage even limited usage examples: Someone may only want to use a tiny sliver of your functionality. That’s ok! By fostering usage at shallow depths of integration, you’ll make fans that go on to deeper exploration.
• Build a Zapier App and eliminate some code: The Zapier Dev Platform exposes your API calls as triggers, searches, and actions. Your customers can then create automations with your API without writing any code. Even better, by having a Zapier app, you’ll allow integrations to the hundreds of other apps on Zapier.

However you choose to serve your API, keep these pie making lessons in mind. Use the best ingredients, but focus on what it makes possible. Understand your customer’s appetites, talk to them, and then deliver the slice they need when they’re ready to eat it.