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

One of the challenges with API design and strategy is focusing on the complexities of designing a User Experience for your API. In most product development roadmaps, the focus is on B2C or B2B and the ideas behind those delivery models are well understood. For the last few years in the API industry, our focus has been on B2D where we’ve been challenging ourselves to design a great developer experience based on usage models for an API.

As the industry matures, more organizations are starting to expand their focus to include the end-user experience for an API and taking into account what the API can offer to the user of the apps those developers are building. Including Customer Experience ( CX) in your equation means reviewing everything from the error messages your API can provide to data and security needs for the end user.

Expressing Your API’s Value with Use Cases

All good product design starts with empathy and use cases. Knowing how people are likely to use your product helps you identify the most important features for your product. This is just as true for APIs as it is for applications. The difference is that you need to go beyond your direct end-user, which is the developer, and consider their end-users. What kind of applications will your consumers build with your API?

Building Use Cases that Matter

In developing use cases for your API, think about the following:

  • Don’t be limited by your current endpoints. Just as with any product design, you need to build what the end user wants, not what your current capability is. The idea of designing APIs in a clean room that’s void of legacy constraints is often referred to as API-first design.
  • What’s the big story? APIs can lead to constrained thinking and micro-focus. The end user of applications consuming APIs have a bigger vision of what they expect from the software they use. Think beyond your API to how it interacts and leverages other APIs (and vice versa).
  • Envision the various user interfaces in which your API plays a part. In the end, you have limited control over that interface but if you spend some time imagining how those implementations might look, you can better determine if your API meets the end-user’s needs.

Keeping Your Use Cases Relevant

Use cases should be considered living entities. Use metrics to measure how accurate and valuable your initial cases were and make sure you’re really delivering what the market wants.

  • If your API has been in use for a while, review real usage data to see how your APIs are being consumed. It’s important to iterate on your use cases based on how end-users really use the functionality and data you expose.
  • As you build more capability into your API, re-visit your use cases to see how they’ve changed.

Designing your API for the End User

Most API product managers focus on the developer as their end user. That’s a completely accurate viewpoint but it’s not the whole picture. The developer you’re focusing on is focused on a different set of users and will choose an API that provides meaningful capabilities for them. Once you’ve identified the appropriate use cases for that audience, you need to also consider how to accommodate their needs in your API design. Here are some ideas to keep in mind while you’re designing your API:

Give the Developer Freedom

Application developers have their own vision and experience requirements for their application. It’s important that you allow them to express their own tone when incorporating your API into the voice of their application. Practically speaking, that means:

  • Giving them enough information about error conditions to take corrective action AND provide user-friendly messages to their audience. Don’t dictate what the end-user messaging is – you have no visibility to the context or tone. Let the application developer control that experience.
  • Be flexible on your branding requirements so they can leverage your brand as much or as little as they need to. For example, perhaps one or more of your paid tiers of service allow developers to white-label your API. In some cases, they are using your API partially because of your brand so make sure you deliver everything they need to incorporate it. But always remember that their end users most likely want a seamless experience inside the application and won’t appreciate having to shift gears to interact with your API.

Do Your Market Research

API Product Managers often focus on the developer experience research, even when performing competitive analysis. But if you keep in mind that your API is simply an ingredient in a recipe (see Part 1 of this series), you can start to figure out how your API needs to fit into the user experience and design its capabilities from the outside in. Where is your API lacking? And how can you differentiate your API by adding capabilities that are unique?

Data Privacy vs Security Requirements

Users need to trust the apps they use. In some cases, developers will adopt your API if it increases their perceived trustworthiness. Know the difference between ensuring data privacy and putting in security measures. Just because you authenticate your users doesn’t mean you’re protecting their data. If your API involves any kind of PII, PCI, or HIPAA compliance, describe this fully in your Documentation and marketing material (along with a description of what measures you’ve taken to secure that data) so your developers can reassure their end customers. Additionally, given how developers are very willing to play a role in securing sensitive data and interactions, don’t be afraid to offer developers a list of best practices that are designed to optimize security when working with your API.  Just because you’ve covered all your bases when it comes to securing your assets doesn’t mean a developer won’t make a mistake that undermines all your hard work.

Deciding what matters

All of this adds up to what really matters about your API. While developer adoption considerations are important, it is also important to step outside those boundaries and consider your API from the Outside In… what is important to their end users? If you solve their end users’ problems, you solve their problems.

Be sure to read the next API Design article: Microsoft Publishes REST API Guidelines 2.3