Who Actually Uses Your API?

When it comes to an API, when asking who uses it you might think the answer is obvious: “Developers, developers, developers!”

While it will probably be a developer who writes the code to integrate with your API, they aren’t always the ones to discover the API. In fact, a developer might not see your API until after a non-developer has attempted to use it, and they're called in to help. Yet, most great API documentation is aimed exclusively at developers.

Your Mechanic's Favorite Car Company

There’s a reason car commercials rarely talk about the internals that really make the car run. Sure, you might hear about horsepower or four wheel drive, but these are snapshots of features designed for the driver to understand. If car makers marketed to mechanics, the vast majority of the time they’d be talking to someone who wasn’t deciding what to purchase. Unless it’s a used car, mechanics aren’t typically consulted in the car buying process—and car designers, engineers, and mechanics are a small part of the overall car buying market.

Of course, it’s unfair to claim developers are simply application mechanics. Certainly, that’s part of the job, but there’s much more planning and building—imagine a car mechanic crossed with an engineer. Evaluating APIs and other tools is part of the process of developing an application. But unless the API is itself a developer tool–such as infrastructure-as-a-service–the request to integrate with an API usually comes from a non-developer.

As you think about who actually uses your API, consider whose job the code enables:

• A marketing email API helps the marketing team
• A CRM API helps the sales team
• An accounting API helps the finance team

Whoever the audience of your product, be they designers, lawyers, or real estate agents, your API helps them do better work more efficiently. They will need developers to implement their application for them, but that comes after they’ve realized your API may solve their problem.

Documentation for Non-Developers

In addition to the documentation for developers, you need to provide documentation for non-developers, too. These don’t necessarily need to be different pages, but you should consider both audiences as you decide what to share.

Zapier co-founder Bryan Helmig said this in his post, Your API Consumers Aren’t Who You Think They Are:

First up is easier documentation. Note I didn’t say better documentation, because that can be highly subjective and varies with the audience. The best documentation for an extremely talented developer might just give them the facts as fast as possible: here’s how to auth, here are the endpoints. We’re not suggesting that here.

You’ll want the just the facts version for developers–that’s typically the full API reference. Both developers and non-developers will want to understand how to get started quickly, for example. If you go too basic, you’re unlikely to get complaints from developers. They’re very good at skimming.

In Bryan’s slides from the API Days conference, embedded above, he describes the goal is to make the non-developer feel empowered, not overwhelmed. One great way is to organize by use case. There are likely fewer than 10 common ways you see your API being used. Put those together for multiple entry points into the information. That way, even if the use cases don’t map to the exact idea, it gets closer than an introduction to all the possibilities simultaneously.

As non-developers peruse your documentation, they’re likely trying to answer two questions:

1. Is it possible to do what I want?
2. Will I be able to do it myself?

Though we’ve been referring to these people as non-developers, the truth is they’re not afraid of code. Someone who fears anything technical would have already bounced from developer documentation. These non-developers are trying to understand if something is possible. They’re willing to copy, paste, change a few things, and see whether it works. The next step may be to put together requirements for a developer, or perhaps to finish it off themselves.

The more you enable this sort of tinkering and exploration, the more likely your non-developer customers are to fulfill their goal of making your product work exactly how they’d hoped.

Developer Experience Still Matters

Now you’re ready to reframe all your materials to the non-developer you’re actually trying to reach. Stop!

Your developer portal, documentation, and other elements of the API development experience are still very important. Once you’ve shown non-developers what’s possible with your API, they will send a link to the developer who will build the implementation. That link is almost certainly some form of documentation, content that needs to appeal to both non-developers and developers.

Here are some questions your documentation should answer for developers:

• What can I do with this API?
• Does this API even achieve the non-developer’s goal?
• Is there anything that helps me get started fast?
• Will the API be easy to use?
• Is there a full reference or am I going to be guessing?

In this context, your documentation is not just about helping developers build their applications. Your documentation is about helping developers feel comfortable saying “yes” to their non-developer colleagues.

Speak to the Edges of Knowledge

Now that you’ve decided to appeal to non-developers who want to use your API, you need to get their attention. Start with the areas you already control, like your end user help docs, or in-app call-outs. You want your non-developer users to realize there is a way to super-charge their experience.

In addition to empowering the non-developer, you also want to inspire them. That means going to the edge of their knowledge and helping them expand that edge. For example, if these non-developers are working as designers, you could help them with the more advanced functions of a frontend framework. Similarly, marketers may know a little bit about automation workflows. You can help extend that knowledge by starting where they’re comfortable, and showing how an API call makes the automation even more powerful.

Documentation for non-developers may not seem as straightforward as more technical references, but it’s worth the effort to expand the potential audience, and empower some of your best customers.

Another great way to make your API accessible to non-developers is to integrate with the Zapier Developer Platform. Describe your most common use cases in terms of Triggers (new data available) and Actions (writing data), then allow your customers to connect to 750+ apps on Zapier.