Voxomos API Guide
Context
Voxomos is an AI startup that builds multi-modal AI chatbots for banks, automobiles and the Indian Government.
My Role
As an intern, one of the first big projects I worked on was to make it easier for developers to use our AI tools through an API. The goal was to design an interactive API doc that would help foster collaboration and integrations with other companies.
What was the problem?
The API guide currently being used was in a Google Docs file and had become a cause of frustration for developers. Additionally, if we needed to reach more people, this was not the ideal way to do it.
Setting Purpose
To define a clear purpose for the Guide, I needed to understand what everybody needed.
I really enjoy talking to people about their work and observing how they go about doing it.
So, I sat down with a developer who was responsible for writing the existing guide to understand the entire flow behind API integration. He also helped me understand some of the complaints and queries they had received from developers using the docs.
A Hierarchical Task Analysis (HTA) diagram helped me bring structure into this discovery process
Understanding what works and what doesn’t
Speaking with a Product Manager who had experience building APIs helped in understanding the best practices for an effective document.
I also looked for API documentation that ticked all the boxes highlighted by the Product Manager and from what I had learned from my research.
My thoughts about some well-known API docs
A couple of Zoom calls with the lead designer and the developer helped me define the Information Architecture. The focus needed to be on guiding the users through the necessary steps of integration and implementation, from quick starts to in-depth guides.
Information Architecture Diagram
Design Explorations
The team was pretty excited about the potential the web API docs showed, so I began exploring ideas by breaking down the user needs and mapping them with the takeaways from our research.
Designing for Clarity
The API docs must cater to a wide range of audiences with different degrees of experience. The API itself needs to be meticulously referenced.
API Overview
This page is used as a detailed guide to the VoxBot APIs, offering structured information and quick navigation links for all available endpoints.
Whether you are just starting out or are a seasoned developer, the content is tailored to provide clarity and comprehensive support for integrating into the VoxBot system.
Making the API's easy to try and use.
Offering a testing Sandbox allows users to experiment safely with the API, encouraging familiarity and understanding
API Sandbox
The API sandbox is a virtual environment that replicates the functionalities of the API without any of the real-world risks.
Within this simulated environment, developers can make API calls and test responses just like they would with the live API.
Guiding the user towards a solution
All errors need to be documented, with a description and possible fixes.
Errors
A clear understanding of an error can highlight the usefulness of your API within a user's workflow, potentially fostering repeated usage.
This is important for every developer who doesn’t want to spend ages on a support call but would rather like to troubleshoot their issues on their own.
Developers struggle with ambiguous error messages, making it harder to implement the API effectively
