You Need These Three People to Care About Your API

You’re about to go on stage and your mouth is dry in nervous anticipation. After repetitive practice, you know your most important talking points better than your name, but still the moment weighs on you. It’s worse than speaking in front of a filled auditorium. Instead, your audience is made up of only three people–and two of them you didn’t expect to see.

Most public APIs are standing confidently on stage, delivering a message that ignores two-thirds of their audience. Even the third they expect don’t always get the majority of their questions answered. Who are three people who care so much about your API, anyhow, and how can you include them?

Gazing out from the stage, you see:

1. An external developer
2. An internal teammate
3. An end user

Each of them could care about your API, but only if you’re able to explain why they should.

Why Should External Developers Care?

Most public APIs only focus on external developers. There’s a good reason this audience is where they look first–developers, after all, write code that integrates with the API. Yet, so often there is a hyper focus that’s heavy on details, but not on context. Many of these public APIs leave tire-kicking developers wondering why they should continue exploring.

Ask developers what they want from an API and they’ll say “accurate and complete documentation” every time. In fact, more will mention documentation than reliability, meaning they’d rather know exactly how to reach an API than to actually be able to reach it. Yet, if you dig into how developers work, you’ll find their needs go beyond the “just the facts” sort of documentation they’ll claim to care about.

Developers would rather know exactly how to reach an API than to actually be able to reach it.

What developers need first from an API is an understanding of use cases. Documentation can be accurate and complete, yet still not help the developer take the next step. That’s because all of the stuff surrounding the reference materials gives them context to determine whether the API is a fit with their project.

Sometimes providers want developers to be inspired by the unlimited possibilities of their API. As a result, their documentation answers all the “how” questions but shies away from the “why” and “what.” It turns out most humans need more direction than a blank canvas. A few examples of your API solving problems can inspire the right developers that your API is the right solution to their own issue, and get them to do more than kick the tires.

Yes, an accurate and complete API reference is still needed, as is getting started material and other examples of great documentation. But it’s the context around the details that will initially help developers decide whether to continue.

Why Should Internal Teammates Care?

External developers get all the attention from public APIs, even if the focus isn’t always on the right content. Internal teammates are often impacted even more by API decisions than those outside your organization. Yet, it’s really easy to forget the needs of your co-workers.

While there are many reasons others within your company will care, the most common are:

• Internal use of your API
• Fallout from external developer “misuse”

One of the best signs of public API success is internal dogfooding. When you feel what external developers experience, you’ll push internally for the change needed. These days many public APIs start as internal projects, which means there could be private endpoints and documentation still in play. To get the full experience, have internal teammates use only publicly-available information to use your API. New hires, for example, are a great opportunity to gain a fresh perspective.

Far more than just internal developers care about your public API. Product, marketing, support, and more are impacted by how external developers use–or misuse–your API. At a minimum, you’re missing out on a new potential integration if a developer isn’t able to get started or even understand what’s possible. A worse outcome could be a problem integration that ends up causing a support burden from those unable to use it.

Integrations should have a multiplier effect. Your teammates want to help make sure it’s multiplying the right things.

Why Should End Users Care?

If the internal audience is an afterthought, the end users show up even less in the minds of those building and promoting a public API. It makes sense why the users go unacknowledged–they’re seen as the opposite of the audience that actually uses the API. However, this group makes up the vast majority of users of the things built on your API.

Remember those use cases I mentioned in the section about developers? Those come from the people who actually use your API. Users know what they want their software to accomplish and your API helps make that happen everywhere.

Zapier’s user-facing product is built primarily for non-programmers to connect to APIs. Over the last five years, we’ve seen that everyone wants to use APIs, even if that’s not the language they use to describe it. Instead, they say want to see their apps work together, and they don’t want to spend their time doing what could be done for them—which is exactly what APIs allow. For public apps available on Zapier, we hear about these use cases, and now communicate feature requests back to the API provider. We know end users care about your API, because we hear from them every day.

Users know what they want their software to accomplish and your API helps make that happen everywhere.

If possible, find some end users to talk to, and learn what they want to automate. Put callouts in your documentation that offer help and you’ll likely find yourself with non-developer users telling you what they’re trying to accomplish. Whether you build documentation or tooling to help those that don’t typically write code is up to you. Simply understanding their use cases goes a long way toward making sure your API can enable what end users want to accomplish.

Similarly, you can connect your API to the Zapier Developer Platform and reach end users without making them code. The Triggers and Actions are encapsulated use cases, which will help you organize your API around how people actually use your product.

Regardless of how you approach the three people in the audience, you want to make sure you have a message for each of them. Each has the capacity to care about your API. You want to make sure that when you’re standing on the stage, you maintain their interest long enough to tell them why.