Guest Post by Timo Loescher, Director, Strategy & Presales at DMI
Co-authored by Sara Trempe, UX Architect and Managing Consultant, Digital Strategy & Transformation at DMI
Internal and external APIs are often tucked away in the shadows of applications and their supporting services. They might seem like just a bit of code, but, in fact, these essential assets are products — and they should be treated as such and supported with resources that enhance their user experience (UX).
You might be wondering, “How can one UX something that doesn’t seem to have a UI?”
Let me walk you through an example case from the insurance world to show you how a single API — when treated as a product and supported with good UX – can unlock revenue and benefit a wider array of users.
In the following scenarios, you will meet three different individuals: the API’s potential end-user, the API’s potential buyer, and a developer who would potentially implement the API.
Potential End-User: Dan
Dan is an insurance broker who has been working with an underwriter to finalize a proposal for a client. After a lot of back and forth, the proposal is ready to be exported as a PDF. But there’s a problem: When exported, the proposal has the underwriter’s branding. Dan needs the proposal to feature his own company’s branding.
Tip: An API that lets Dan export the proposal with his custom branding would be extremely useful to him and to others like him. If such a product existed for him, it would save him time and also eliminate the risk of introducing errors into proposals.
Potential Buyer: Rebecca
Rebecca is Dan’s boss — a regional executive. She’s been working on ways to modernize the proposal process and enhance the customer experience.
After speaking with Dan about his need, Rebecca calls a colleague, Mike, who is a customer service manager. He says he thinks their company has developed an API for just this purpose. Rebecca just needs to know if the API that Mike references will fix the problem Dan has identified. So she talks to her IT partner, Garash, and he reviews the API specs. Unfortunately, he can’t seem to make sense of whether or not the API is something that will integrate with their system.
![New call-to-action](https://cdn-ceheb.nitrocdn.com/LYkBDVHVdldIrognCFlxEKUhZLCymUBO/assets/images/optimized/rev-80b26c7/no-cache.hubspot.com/cta/default/8444324/f8ee566c-b425-459e-978e-2b8f0eb44811.png)
Tip: As you see with this buyer scenario, the internally developed API was not presented in a way that made it clear how it would benefit internal users. Rebecca heard about the API through word-of-mouth. There was no educational resource for potential users. Before implementing or buying a product, customers need to understand the benefits of that product.
Potential Developer: Taylor
Taylor is a lead developer who would potentially implement the company’s internal API. She can see that the API product should meet the company’s needs, based on the newly-written product description. But the documentation for implementing the API is not very specific.
Taylor tries her best based on her previous experience of working with third-party APIs. She wants to get the API into a sandbox to test and see how all of the data will map. While testing the API, she looks for documentation about accessing notifications when a change is made to a drafted proposal, but there doesn’t seem to be any detailed help content available. She wishes she could speak with someone about how the product works.
Tip: When designing APIs as internal or external products, they should be accompanied by reliable documentation for the developers who will be implementing them. Organizational and visual documents like user journey maps and service blueprints can help. But developers also need the ability to quickly find what they need — data card sorting, naming conventions, and structure. Community forums and support channels are also helpful for these users.
Best Practices
When we view APIs as products and consider potential use cases like the ones above, we can begin to see why UX design and supporting resources are so important.
When rethinking your API strategy and turning new and existing APIs into products, consider the following best practices:
Prioritize empathy. Put yourself in the shoes of the people scattered along the user journey. A focus on empathy and feedback loops will drive success and make the API products more attractive to internal and external users. A better understanding of the users – not just their demographics but their motivations, context of engagement, and typical behaviors – can allow you to optimize your solutions to speak to and support those personas directly.
Create a business model canvas. This process will help your team to capture and articulate to company leadership the viability of an API from the perspective of the buyer. If you can think of your API product as a little start-up, with its own value proposition, partnership needs, and cost structure, you can more easily frame how to project that to your customers.
Do research on how developers use and interact with API products. This will help your team understand how developers work and what they need in order to have a good user experience. Ideally, you can leverage UX experts to conduct formal user interviews, usability studies, and information architectural assessments. In their absence, you can always just sit down with a few developers in your org (take them to lunch) and chat through their preferences and horror stories about API documentation sites. Just be sure to stay objective.
![New call-to-action](https://cdn-ceheb.nitrocdn.com/LYkBDVHVdldIrognCFlxEKUhZLCymUBO/assets/images/optimized/rev-80b26c7/no-cache.hubspot.com/cta/default/8444324/ce331dab-4a0a-4fe7-944b-60f3e4d6583e.png)