Why Your API's End-Usage Context Matters To Great Developer Experiences

As the focus on APIs grows, we spend a lot of time optimizing the Developer Experience by focusing on delivering robust documentation, easy accessible and un-throttled sandboxes, various support channels, and community events. As the industry matures, developers have come to expect all of these things and companies recognize that they are an important investment on the road to API adoption.

But one thing we tend not to focus on is the larger context in which our API fits. In general, your API is the means to an end for an application developer so it’s important to understand what that end state is.

Cinnamon or Salt?

Consider application developers to be chefs – they are basically constructing one final product, the perfect meal, and looking for just the right ingredients to bring it all together. Depending on the purpose of their final product, the decision points for choosing the ingredients will vary. As an API provider, it’s important to understand how your API fits into that picture and provide the right offering to make yours the ingredient of choice.

Is Your API Cinnamon?

Cinnamon is one of the most versatile ingredients around. It can be used as the main flavor of a recipe (think cinnamon buns), as a flavor complement (think apple pie), or as a secret ingredient that boosts other flavors (think mole sauce). In each of those cases, the recipe relies on cinnamon but in different ways and to different extents.

Let’s take a look at what I consider to be the cinnamon of APIs – maps.

If you are a maps API provider, you have certain requirements – accuracy and speed – that are table stakes for your product. (First and foremost, cinnamon has to taste like cinnamon.) But from there, your versatility needs to be obvious to the API consumer community. The first step to expressing versatility that makes sense to your target community is understanding the recipe they are building.

Is the application all about navigation?
If so, your Maps API is front and center. Without you, the application is useless. That means this application developer is relying on your API’s reliability – accuracy, uptime, scalability, and speed are all driving factors for this customer. Your marketing needs to communicate how you stand against the competition in those categories. But you also need to back that up with support. Do you offer SLAs as an option (even if it’s a paid option) that make developers feel comfortable building their entire application strategies on your API’s capability? How will you support an incoming issue or proactively communicate an incident? These are the types of things a developer will want to know up front and will want you to have in place before they choose your API as their main ingredient.

Is it a restaurant locator?
A restaurant locator app also relies on heavily on a Maps API but it’s more like apple pie than a cinnamon bun – you can make an apple pie without cinnamon if you have to, but it won’t be as good. If your API is cinnamon, you should think about creating tiers for your offering. A business locator app can still function if the Maps API fails but it doesn’t meet its customers’ needs like the competition does. A developer building an app like this will still want an API they can rely on and a company that provides great developer support. But they may not pay the extra dollars for a higher rate limit or 24x7 support that a navigation app developer will pay. Having a second tier for this group means you can tailor your API offerings based on the developer community’s needs.

Is it a website that offers directions?
A cinnamon API can also just be an enhancer rather than a central feature of the dish. For our Maps API example, we can look at websites that offer a map widget so you can see the business location and get directions. The Map is a nice-to-have in that interface but not necessary. And, in this case, the developer may want more than just a lower tier for support and reliability… they may actually benefit from a free tier that offers less data. Maybe they can pin their own address and get directions but can’t pin multiple locations or provide a street view. Think about your tiers not just in terms of SLA and number of calls but also in terms of the endpoints you make accessible.

Or is it salt?

Salt is one of the most widely used ingredients and is in just about every recipe and on just about every table. It’s the kind of ingredient that you can either add before you add heat, or later while you’re applying heat, or even after the cooking is done and before you actually eat the food. It’s pretty rare that a dish centers on salt but there’s hardly any dishes that don’t include salt.

Let’s talk about the salt of APIs – login.

If you are providing a login service, you have a number of things to consider – one of which is how much is enough. Just like salt, sometimes just a pinch will do – the application developer is just looking for an easy way to implement login capabilities without having to build it herself. In other cases, the developer requires a secure login that provides both ease of use and secure authentication. But one thing you know as a Login API provider… nobody builds an application that is *just* about logging in.

Is the application for members only?
In many cases, an application inserts a login for their own purposes – they want to know who their community is so they insert a lightweight login capability, like a pinch of salt to enhance the flavor of their own offering. This lets them communicate with their users based on behavior and demographics but it doesn’t provide any kind of serious security capabilities. In this scenario, the developer wants your API to be easy to implement but they also want your API to do its job and get out of the way.

Is it providing unique capabilities based on integration with your login?
Sometimes a login is more than it appears. A great example of this is GitHub Login, which not only logs a user into the application that implemented this API, but also provides seamless single sign-on-like (SSO) login and integration into GitHub. When an application developer decides to use this kind of login API, they are looking for more than just authentication. Not only are many developers looking for other integration benefits that make their own offering more robust, they are eliminating UX friction by allowing users to leverage an existing identity (like their Github identity) as opposed to creating a new one.

Does the application involve sharing/storing confidential information?
In some cases, authentication is more than just identifying an individual – it’s identifying an individual with an extra layer of trust and security. There has been a rise in trusted identity offerings lately, as we see the emergence of more robust mobile and online capabilities in industries like Fintech and Healthcare. When an application not only needs to know the identity of a user but also needs to trust that identity and receive/revoke consent during confidential transactions, the developer will look for a login API that goes above and beyond a simple login.

Cinnamon or Salt: How does this change your API approach?

It’s important to know how a developer plans to incorporate your API is so you can not only design the right API but also provide the right offering for consumers of your API.

SLAs and rate limits

Defining Service Level Agreements and applying rate limits requires a keen understanding of how consumers will incorporate your API. Any application that relies on your API, either for functionality or authentication, needs transparency when it comes to your API’s performance, uptime and rate limits. An application that can fail gracefully when your API fails has less at stake. If your API can be essential to some applications but a nice-to-have for others (aka cinnamon), then it’s probably worthwhile to set up tiers that allow developers to choose between a free offering with less restrictive SLAs and lower rate limits vs a paid tier with more support and a higher rate limit.

Quality focus

Of course, the panacea is that your API quality metrics are broad and wide-ranging. But many API providers need to identify the highest quality concerns so they know where they can make compromises if the need arises. If your API is providing important functionality to an application, like maps, then you probably want to ensure speed and accuracy above all other things. If your API is providing authentication, reliability (uptime), ease of use, and security might be your main focus.

Use your cinnamon vs. salt analysis to determine where and how to focus your API testing so your consumers’ consumers get the best experience they can. API quality is an important factor in developer adoption so keeping their application goals top of mind when determining your test plans is key.

Keeping the Recipe in Mind

When you’re an API provider, it’s easy to forget the larger picture in lieu of all of the API details that you need to worry about on a daily basis. But building a great API and engaging the developer community in a relevant way means understanding the context in which it will be used. In the next part of our series, we’ll talk about why the end-usage context matters to your API design and discuss the various decisions you have to make as part of launching your API.

Be sure to read the next API Strategy article: Dropbox API v1 Now Deprecated


Comments (0)