An API for everybody
TL;DR:
- We received a lot of complaints from clients using our API and noticed that the documentation was made by our developers.
- I decided to interview them each type of users to understand their process (Developers, WordPress users, internal sales team).
- Learned how to use Postman and wrote a documentation tailored for developers
- Wrote also a tailored documentation for CMS users (WordPress, Shopify, Prestashop)
- Created a presentation for our internal teams in order to help them talk better with our users.
- The team: Myself, 1 Product manager, 1 product owner, 1 Junior UX Designer
INTRODUcTION
When the terms “UX research”, “user experience” or “user interface design” are mentioned, you can immediately associate them with websites, user tools, software interfaces, intuitive interactions and attractive graphics. While these are all valid associations, you may have neglected one of our most important users – developers!
“An API that isn’t understandable isn’t usable.” James Gosling, founder of Java
Context
Founded in 2016, Paps is a business service operating in French-speaking Africa, offering warehouse services, pickups, and deliveries. They are the first on-demand and geolocated delivery company in the region with the largest fleet in West Africa. They gained recognition by winning the fifth edition of Hub Africa and has attracted investments from Google and Alibaba’s Global Initiatives. They serve a diverse range of industries, including financial institutions, pharmaceuticals, telecommunications, retailers, and most importantly, e-merchants, who can integrate the Paps API into their system to send their products.
The e-merchants sector experienced significant growth and the product team soon found itself overwhelmed by requests for integration support, both coming from customers directly and from the Sales people.
As a UX designer, I was challenged to make the API integration more user-friendly, while the documentation was complex, the business terms not very explicit, and CMS users lacked adequate support for integrating the API into their platform.
Understanding and framing the problem
Creating an API that only the developers who developed it can understand is pointless, because the real beneficiaries are the people who use and interact with the API. The first challenge was to understand the requirements and challenges of API users. The best approach to understanding their problems and providing solutions to their questions is to conduct research.
But before doing the research, I had to understand how the API works, know how to use tools to test requests, know how to send Json requests, know how to read errors, etc. Basically, I had to read up and integrate the world of developers. In short, I had to learn all I could about the world of developers.
A designer in a team of developers? Working on documentation? You might say it’s like mixing oil and water, but it’s quite the opposite. I myself have scoured my fair share of documentation, Stack Overflow posts and blogs over the months.
Postman
Postman is an API development tool for testing, debugging and documenting APIs. It also allows you to create collections of API requests for later use.
I was able to take Postman in hand quite easily, as I had already studied software development before turning to UX Design. I was able to quickly understand how the tool worked and how to use it effectively to test requests, send Json requests and read errors.
Research
Clients
The user research I conducted to understand the challenges of API integration involved multiple steps. First, I identified a representative sample of customers and prospects who had already used the API or were considering using it with the help of our sales and support team. I then contacted them and invited them to take part in individual telephone interviews. Some did so accompanied by their developers.
During these interviews, I asked open-ended questions to understand the difficulties they had encountered when integrating the API. A number of complaints came up repeatedly, including the complexity of the documentation, the lack of clarity in business terms, and the absence of specific documentation for users of CMS such as WordPress, Shopify, PrestaShop and Magento.
I took the opportunity to explore their usage habits, expectations and needs. Participants expressed their desire for clear, accessible documentation, examples of how to use the API, and responsive technical support available when needed.
Internal developers
After conducting interviews with internal developers, I discovered that API documentation was often sent to customers in the form of a link to Swagger UI, an online tool for testing API endpoints. While this tool could be useful for developers, it didn’t offer truly structured and comprehensive documentation for non-technical users.
As a result, customers using the API for the first time often found it difficult to understand how the API’s various functions and endpoints worked. They were confronted with complex and unclear documentation, which prevented them from concentrating on their main objective: integrating the API into their project with ease.
Sales and customer service.
During my research, I found that sales and customer service staff didn’t always understand the technicalities of the API that Paps offered. They weren’t able to answer customers’ questions about API functionality, or provide advice on integration and troubleshooting. As a result, whenever a customer had a question or problem with the API, they were immediately redirected to the development team, without any real, accurate background information.
This created an overload of work for developers, who were often forced to devote time and energy to solving minor problems or answering trivial questions. Ultimately, this affected productivity and customer satisfaction, as they felt they weren’t receiving the level of support they needed.
how might we...
To guide my design, I formulated several HMWs, including “How might we make using the API simpler and more intuitive for non-technical users?”, “How might we reduce training time for CMS users who don’t have a technical background?” and “How might we set up a smooth channel with Sales to guide prospects through API integration”. I used these questions to guide my search for solutions.
solutions
For “coders”
After a long benchmark to find the perfect tool, I discovered that Postman automatically generated basic documentation for any collection created. I used this to set up a complete and detailed documentation. This documentation was designed to enable customers to quickly and easily understand how to use the API without having to call on our developers every time. It was drawn up with the supervision of the Software Architect, the developer in charge of the API and the Engineering Manager.
The Postman documentation included examples of common requests and detailed instructions on how to perform them. It also explained key API concepts, such as endpoints, authorizations and parameters. In addition, the documentation was regularly updated to include new features and changes to the API.
For CMS users
Having identified that CMS users were having difficulty integrating our API, I decided to create dedicated documentation for each of the most common CMS, such as WordPress, Shopify, PrestaShop and Magento. To do this, I used Confluence, a collaborative content management platform, which enabled me to gather all the necessary information and guides in a single space.
I’ve chosen to write a less technical documentation for CMS users, focusing on the concrete steps to follow to integrate the API on their website. I also included examples and screenshots to help readers visualize the steps involved. This approach was much appreciated by CMS users, who were finally able to integrate our API without difficulty and without needing to call on our technical team. Here’s a sample for the WordPress users.
For internal teams
To improve understanding and use of the API among internal teams, I gave asked to the junior designer to set up a clear and detailed process on Google Slides. This platform was chosen for its ease of use and familiarity to team members. The process describes the prospect’s journey from their first request for information to the resolution of their problem. For each stage, the process indicates the actions to be taken and the information to be provided to facilitate understanding and use of the API.
The process was presented and explained to team members at a training meeting. Questions were asked and discussions held to ensure that they fully understood the actions to be taken to meet customer needs. The processes also helped to reduce errors and response times, leading to increased customer satisfaction and an overall improvement in their experience.
Conclusion
Thanks to the implementation of clear, easily accessible documentation, as well as well-defined processes for customer support, we have been able to significantly improve the user experience. In numbers :
-40%
less time spent by the development team helping prospects thanks to the process.
-30%
decrease in help requests from CMS users thanks to Confluence documentation
+20%
more customers integrate our API into their code thanks to Postman documentation
+15%
retention rate among existing customers
English (UK) 
Français