Redesign API tryout for developers to test APIs on developer portal
Product
Developer Portal
(direct-to-consumer)
Company
Precisely
Role
Lead UX designer
Device type
Responsive website
Team
1 UX designer
4 Product managers
6 Engineers
2 QAs
3 Content writers
Sales engineers
Time
7 months
Status
Under development
Overview
Background
Enhance API Tryout user experience
Precisely sells multiple sets of APIs, such as Address Autocomplete, Address Verification, and Address Geocode, etc. To help customers understand and interact with our APIs, we created a developer portal to learn about the business use cases, try out our APIs, and access API reference documentation.
"API Tryout" is an essential functionality in the Developer Portal. It allows developers to test API calls directly within their browsers, reducing development time by avoiding setting up complex testing environments.
Challenge
30 mins spent on trying out APIs
Currently, the usual time developers spend on completing the authentication and trying out the API is around 30 minutes. Users are frustrated about jumping between different platforms throughout the process and spending time finding the API documentation.
Solution
A 2-panel-layout interface with sign-in authentication method
A sign-in mechanism is introduced to the developer portal for developers to complete the authentication by simply signing in to their accounts. Besides, I adopted a 2-panel-layout for the API tryout page with the documentation on the left and the code panels on the right; so then users could easily reference from the documentation while interacting with the codes.
Impact
Reduce 40% of time spent on testing the APIs
The time spent on authentication and trying out the API dropped from 30 mins to 10 mins. It significantly enhances the API tryout experience by easy-authentication-process and accessing the documentation more efficiently.
Business Goals
Vision
Transform into a self-service platform
The project kicked off with the vision of transforming our developer portal into a fully self-service platform, where it's not simply API reference documentation but a central hub that allows developers to easily understand and interact with the APIs without additional support.
Increase API adoption
Attract new potential customers to gain revenues.
Save Support Resources
Reduce the needs for users to contact supports while exploring and implementing APIs.
Research
01 Understand Users
Focus on Developers as primary users
Developer User Journey
02 Understand Space
Prioritize features based on impact and efforts
I investigated other companies' developer portals to figure out the essential features and content they provide. This helped our team to set our long term strategy by identifying the features we would like to add and prioritizing the most impactful but with less efforts features to start with.
Focus on enhancing Authentication and API Tryout experience
We prioritized focus on simplifying authentication and API tryout, ensuring developers could quickly test APIs and motivate them to purchase our APIs.
BENEFITS
1
2
3
03 Understand Our Product
Developers spent over 30 mins completing authentication and trying out APIs
We observed developers going through the entire process, and he struggled significantly, spending over 30 minutes to complete the tasks.
AUTHENTICATION
Require users to jump between 2 platforms
Developers had to leave the developer portal and enter another workspace environment to generate an API key, then return to input the key for authorization. There was a lack of guidance on where to go or what to do.
API TRYOUT
Difficult to access API documentation
Users lose access to the documentation while defining the API request. Besides, they need to scroll the page back and forth to access the response field documentation, which is inefficient and time-consuming.
Design Challenges
1
How can we simplify the authentication process without jumping between platforms?
2
How can we make documentation easily accessible and readable while developers are testing APIs?
Final Design
Design Solutions
Authentication
Streamline authentication process
The first part of my design solution is to streamline the authentication process. We introduced a new sign-in mechanism that allows users to sign in and authenticate directly within the developer portal.
Provide inline help of authentication
I added an “Authentication” section at the beginning of the page, making information more visible and accessible without having to search the Help documentation.
UX WRITING
Make the message more obvious and concise
I experimented on the message box stylings and decided to use a blue info message box to make it more prominent since users need to notice it when they first arrive the page. Besides, I collaborated with our content writer to make the instructions clear and concise.
USABILITY FEEDBACK
Clearly indicate user's authentication status
I added a status field to indicate whether users are authenticated or not after usability testing shows that users were confused whether they're authenticated or not.
API Tryout
Adopted 2-panel-layout
The information architecture, showing documentation on the left and code panels on the right, aligns with the developers' reading sequence and interaction flows, allowing them to access and reference from the documentation more efficiently.
Enhance documentation readability
I made significant improvements to the documentation to make it more digestible and easy to read, aligning with the developers' mental model.
Table vs. Accordions
Initially, I used a table format to display parameters, but developers typically view code hierarchically, so it's difficult for them to see the relationships between parameters.
As a result, I switched to an accordion-style nested structure, allowing them to expand and collapse groups of parameters easily and see the hierarchy between them.
Design System
Contribute and adopt design system for consistency
I collaborated with the design system team to ensure my design is consistent across Precisely products. Besides, I developed the guidelines for tags and copy button that were added to the design system too.
Accessibility Design
Design for different API types & screen sizes
Validate Design
Conducted usability testing by online survey
I conducted a usability test survey with the internal stakeholders, including PMs, developers, and sales engineers from various APIs teams. A survey built by Maze allows me to collect feedback efficiently and analyze user behavior from the heat map and diagrams.
Impact
We received positive usailbity results and insightful feedback.
40%
reduced time
81.8%
task success rate
5.8
easy/difficult score
Total: 20 responses, Scale: 1 = very difficult, 7 = very easy
"
I like the interactive structure of request and response body along with document information, so easier to navigate and understand the parameters at the same time.
By Sales Engineer
Next steps
Measure success with quantitative user data
The design has already been handed off to the engineering team and is currently in development. The next step for me is to analyze user data to measure our success.
Authentication success rate
Tryout rate for each API
API adoption rate
Continue towards a self-service platform…
Demos feature for business managers to understand API without interacting the codes
Explore APIs and API product pages to help users easier navigate and understand each API
Reflection
My superpower from this experience…
Stakeholder Management
With 4 product managers and multiple stakeholders involved, I scheduled regular sync-up meetings to ensure incorporating different points of views and keep everyone aligned on the same goals.
Strategic-Thinking
I guided the team to develop a product strategy that aligns with our vision, business goals, and user needs, delivering a consistent and successful user experience in the long term.
User-Centric Research
I conducted the user-centric research by engaging with internal developers through interviews and usability tests, which really helped shape the direction of the design.
