Designing Experience for API Portals
When we mention “Experience Design” or UX, we often think about the myriad of websites and applications around us, example social media, Banking websites, e-commerce etc.
Somehow we tend to overlook the applications which we use specifically at the workplaces. Applications which may not have a huge user base, but their users have some unique needs in terms of Experience. These are the users who use these applications, not because of their own choices but because they have to. More often than not, these users do not even have a say in the selection of these applications.
However, that means that as UX Designers, it is our responsibility to understand and address the specific requirements of this user group.
Bruno Pedro, API and product Technologist proposed this hierarchy, inspired by Maslow’s hierarchy of human needs. This can be an excellent framework for any team which is starting with the UX design of an API Portal.
This article focuses on some crucial aspects of UX, when designing API portals for Developers.
Considering the recent developments in the domain of API technologies , it is high time that we start considering API portals as full fledged products. It is consumed by Developers who are technically sound, but that does not make them any less deserving of a premium User Experience. Developers are Users too !
Following are some key aspects to keep in mind when designing for API portals :
1) Spend Time in Designing Documentation
Documentation is the key for any API portal, both for helping the Developers decide if this is the right product and also finding the right resources.
GUIDES : There should be a Guides section that describes what the API does, in plain english. The content should consist of the benefits of the product, Not the features. It should describe the capabilities which help the developers understand if this is the product which they need.
TUTORIALS : This is the detailed , step by step set of instructions, of the various API resources and the ways to manipulate them. The content here is very different from the Guides section.
2) API Reference is Critical
This section is used to document every endpoint and the example codes in multiple programming languages.
As per my experience , Developers generally do not want to adopt unfamiliar technologies. So the aim of the API Reference section, is to demonstrate the usage of the API for multiple client technologies. When the Developers see examples of client codes in multiple programming languages, it gives them the confidence to go ahead and start exploring the product.The Clearbit API Reference is a good example of this.
3) Highlight Use Cases
This is an important step in making the Developers start exploring the API product. Define relevant use cases such as “How to Use our APIs for Designing error free payment transactions” Or “See How Our Customer XYZ, improved their efficiency by 30%, in just 12 hours”. Highlighting the customer success stories is a very effective social proofing method, to instill a sense of reliability in the Users. I recommend highlighting these use cases higher up in the visual hierarchy of the portal.Uber Developers, does this exceptionally in their portal.
4) Client SDKs Lead to Better Adoption
Many API portals tend to ignore this feature. Although it is not mandatory , but it always gives the product an edge, when there are well defined, robust client libraries for different programming languages. This reduces the effort of the Developers when they integrate with the API portal. This is all the more useful for developers who are new to a particular programming language. Twilio implements this feature pretty effectively in their portal.
5) Be There for “SUPPORT”
There is nothing worse than a frustrated user who does not know his way around your product. Therefore, an essential element of designing a good experience for Developers, is to have an efficient, dedicated Support team. We need to understand that Developers accessing the portal are trying to complete a task, which is often time bound. They cannot afford to waste too much time figuring out things on their own. A reliable Support channel coupled with active user communities instill a sense of confidence for the users. Uber Developer is often appreciated for its efficient Support channels.
6) Visual Display
Although the visual design depends a lot on the specific user groups within the Developers, but certain guidelines do help the users in exploring and using the portal effectively.
Visually Highlighting the code samples, as compared to their text based descriptions, make it easier for the Developers to understand the usage. Also, the Developers are more comfortable with “Code” language and find it to be more familiar.
For text heavy sections, like Support or Communities, implement ways to highlight the most relevant content for the particular user. Example, if there are too many answers to a question posted in Community, rate the answers based on user responses. Organize the FAQs according to relevant categories, for easier information retrieval.
Diagrams and other graphical representations are better than verbal descriptions, for explaining complex systems. These should be used in explaining the implementations for use cases or case studies.
These were some of my learnings when designing for API Portals. I would love to hear your experiences !
