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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
Get new articles about API design, documentation, and success delivered to your inbox.