Bring your APIs from good to awesome with UX research!
When you hear about “UX research”, “user experience” or “user interface design”, the first things which might come to mind are “websites”, “user tools”, “software interfaces”, “intuitive interactions” and maybe “beautiful graphics”. All good and true, but you might have forgotten some of our most favourite “users” — developers!
In the API space, we build something on a machine for a machine to use and this is wrong
because there are people on the other side of API clients.
— Ronnie Mitra, Director of Technology at Publicis Sapient
The best way to create outstanding APIs is to write them with the user in mind. There is no point in designing an API only understandable to the developers who created it — after all, the real stakeholders are the developers who consume and interact with the API. Therefore, a good API must be easy to use for them.
When working with an API-first product (like the platform that we have), you can’t forget UX research when designing APIs.
With this blog post, you will learn how we at commercetools use UX research for our API solution and how this moves the API to the next level, including how we integrate the user research process into our API development. This article also discusses some methods and how to apply these to your project.
This blog post is the first in a series of case studies where we will present the things we have tried and what has worked for us at commercetools.
Step 1. How to start
Understand and frame the problem
First and foremost, you need to understand the needs and pain points of your API consumers. Only when you understand your users’ problems and are able to answer their questions you can create a strategy for a successful API solution. The best way to frame the problem is by doing research.
Step 2. Research
Discover the problems
Understanding the problem goes way beyond just asking users what they want or like. Remember, when people wanted faster horses? Here are some ideas to get to actual root of issues and frustrations faced by users:
Interviews
Interviews are a great way to both get direct feedback and build good relations with your API consumers. Contact users from the target audience and ask them about their usage behavior and issues that they might have faced with your current or new solution. This will help you to gain better insights from the consumer’s perspective.
Don’t forget to pay attention to their nonverbal reactions. Nonverbal communication often tells a different story and reveals how a consumer really feels about the solution — that frown you see can say more than anything they’ll tell you. This is important since some participants are too nice to give direct criticisms. With interviews, you gather a lot of qualitative data to allow you to get closer to discovering the needed solution.
Qualitative Surveys
Surveys are questionnaires that focus on a specific topic that you want to research. The better formulated your questions are, the more valuable the answers will be. After defining the questions the survey needs to be sent out to as many users of your key audience as possible. You’ll get to your users when they actually have the time and energy to share their thoughts. Plus, who likes scheduling meetings? You receive feedback as soon as the user has finished the survey.
Afterwards, it’s really easy to translate the results into understandable infographics that summarize the outcome of the survey.
Monitoring
When you have an API solution that is already in use, you can track user interactions to get insights on their behaviors. For example, you can track which update action is performed the most on a specific feature, whether they prefer querying data by ID or human readable names, or simply whether a new feature is used at all. You can also elaborate on user flows to answer questions like: How much time did a user spend on the documentation before they asked support for help?
While these statistics can help you make many decisions, keep in mind they will tell you only the who, where, and what… but not the why.
Using this technique in combination with other research methods to build a data triangle will help you to achieve a comprehensive understanding of the whole topic, filling in the why’s and how’s.
A great way to start and use these statistics is the UX Benchmarking process. The first step involves deciding what to measure and how it will be measured.
Once the criteria is put into place and measuring is carried out and completed, evaluate the findings against industry standards, competitors or use the gathered information as a baseline to evaluate future improvements (e.g. the time spent on a task takes now 2 minutes less than before).
UX benchmarking helps to demonstrate the value of UX research, and the metrics you gathered can be used when calculating “return on investment” (ROI)
Step 3. Analyze
In the third step, analyze all the feedback that was gathered in the previous steps. There are many possibilities to do that, our favourites are:
Thematic analysis
This is a method used to analyze qualitative data.
It’s mostly used on sets of texts gathered during interviews or directly taken from the interview scripts. The goal is to uncover themes within this data. To do so, you need to search for relationships or similarities within the sets of texts. When done correctly, you have clusters/themes of specific topics, e.g. paint points, consumer usage, behaviors, needs, opportunities. By color coding feedback by type such as pain points, opportunities or general feedback, you could create a board that is easily scannable by improvement topics.
Rainbow spreadsheet tool
Another tool that will help you analyze qualitative data is the rainbow spreadsheet. Introduced by Tomer Sharon, it can be easily created within Excel or Google Sheets, and can be used in many different ways. A good recommendation would be to use it for validation and visualizing key findings from e.g interviews, user observations, etc.
Start by creating a table or a grid where you can list the unique findings. There should be one column to represent key findings, with one finding per row, while next to findings, there should be columns for participants (with each participant receiving their own column and a unique color code).
After that, go through each row and highlight the cells for all participants who mentioned a specific finding, using the unique color of the participant.
As a result, you can quickly scan for the findings that affect the most participants by looking at the rows with the most colored cells. These rows are the findings you may want to prioritize as the next “action to take” for your team.
Step 4. Testing
After uncovering your customers’ pain points, you should focus on possible solutions. Remember that steps 1–3 are quite important for the success of your solution and will only provide you with valid results if you run the tests well. Depending on the findings, there are many methods and prototype approaches that can be used to test the ideas.
In terms of APIs, you need to think about the structuring of resources, methods, naming conventions or error messages displayed by the API. Also don’t forget the usage of your SDKs. Most of these things can be tested with appropriate UX writing techniques. Here are two examples of testing methods and how to use them:
Cloze test
Cloze test is a “gap fill” exercise for UX copywriting. The participants will be presented with a copy section, where they have to replace a missing language element. (e.g. words, characters, items). This test helps verifying how easily readable and understandable a section of text is. You could also abstract the approach to test naming conventions, proper error messages, or human readable descriptions.
Prototype testing
Prototypes serve as a first draft on the path to finalizing your solution. They help to elaborate if an idea will work and is usable by your user. When you have your draft ready, get in touch with your users and let them perform tasks associated with this prototype.
Prototype testing isn’t just for frontend solutions, but can be used to test your APIs and SDKs too. Get in touch with a user (developer) and let them solve a task by showing your API/SDKs or a prototype of them.
Observe the user while they are performing this task since it’s the best way to understand and see how your solutions are applied and if difficulties occur.
An API prototype testing scenario could be done through Pair Programming (an agile software developer technique, where two developers work together on the same task simultaneously, often on the same device)
Step 5. Repeat or build final solution
If the previous 4 steps are followed correctly, you will have gained more and more confidence that you are building the right solution for your users.
When none of your users have issues fulfilling their daily tasks with your provided solution, you will know you had done the right thing and you can start developing the feature.
If you still see your users struggling to understand your solutions, go back to Step 2 and repeat the process until users are able to work smoothly.
Having now given a brief guide of UX research processes, let’s go over some of our key learnings from past and current UX research processes conducted from our current API solution.
Naming conventions
Naming conventions within an API are quite important as those names will be used as requested. When the request speaks for itself it’s easier to connect the usage of this request to the dedicated outcome. One example from our product was “ImportSink”. The intended response to this request was to create templates for all your resource types needed to be imported (e.g. categories, products, product types, prices). The intended idea behind the name “Sink” was developed in a metaphoric way from a bathroom sink where you put a load of water (data) in at once. The sink is filled up, but asynchronously water goes into the drain and is sucked in (imported). This was a nice internal explanation from our side of the team, but no consumer would get this metaphor without providing them a proper explanation. This was the outcome of our research phase where we discovered that users will get the connection to the bathroom sink but not the intended idea behind it. On the other hand, many consumers thought of the word sink as “sync” from synchronization. This led to a lot of misunderstandings due to the similar pronunciation. We came to the conclusion to change the name for the resource into “ImportTemplates”. Always try to use names that are common in this specific type of field or listen to users and how they describe it.
New word creations might not help your consumers or will confuse them.
Troubleshooting — Unclear or missing information within the API
Although we aim to provide the best development experience through our API and documentation, we know that there is always room for improvement.
States and error codes are not sufficient to understand. As a consequence, users always contact our support to help them to solve their issue. We should always think about human readable and logical structured resources, methods and error codes and their related descriptions.
Whenever the user needs to connect their systems to our API, it might happen that the API request is not behaving as expected.
It could be that it was not possible to send a request, or the response that the user receives is different from the examples we provide in our documentation.
This is the situation where the user needs to start debugging and troubleshooting. In best cases we can provide the users perfect status code and error messages that allow them to easily understand what went wrong. In reality this is not always possible as API errors can also occur in situations that are difficult to consider or test. Sometimes the user himself could provoke bad requests with mistakes or typos that our APIs won’t know how to handle.
To avoid these types of trouble, we will provide our users with “best practices” and a variety of examples that they can easily copy and rewrite for their own needs.
Key insights
Always see your API from the users point of view
Often breaking changes are made because developers create APIs without considering users. This means that they are creating something for themselves and not the actual needs of the API users.
The API is a contract
The most important thing is to treat the API interface as a formal contract.
If you ever tried to change a contract you know how difficult and time consuming it is. Invest time in negotiating the contract, and limit the need for changes. That is basically what you do in your research: Negotiating until you find an acceptable API contract and design. If you miss an important part of your API solution and the API is out of beta, all your users need to deal with this.
— —
Do your UX research next time you change your API or build a whole new solution. It does take time and effort, and it may initially slow down your workflow but that’s absolutely worth it, as you will save a lot of effort, money, and time past that initial stage for the long-term future. As a bonus, your users will thank you!
Not doing proper UX research before hand is like driving a Ferrari with a Renault twingo motor. If the engine is not right, you will never reach the full potential.
One dedicated person doing the UX research will cost much less than a full development team delivering a couple of features during three sprints but having issues within the product from the lack of UX research. The earlier you can solve those issues within your product, the better.
The best approach is to have at least 1 dedicated UX person for each team to help you with the required research and guide the team through the process! If you already have a dedicated UX team like we have at commercetools, get in touch.
We are looking forward to exchanging ideas and tips or driving the next topic together ;)
In the next part of this series on “Bringing your APIs from good to awesome with UX research!”, we will discuss the benefits of using UX methods such as: thematic analysis, close tests, prototype testing and, present detailed case studies about how we applied (UX Research/ Discovery techniques/ name it as you wish) to our API solutions at commercetools.
