API portal: what to look for when designing. Wrike Experience
Using public APIs helps companies increase the value of their own resources, create unique content and meet the requirements of various business tasks. Wrike is no exception. More than 30 thousand applications have already been created based on the Wrike API. The number of users of the product is growing, which means that the requirements for the portal are increasing every day.
In this article, I will share my experience in redesigning the interface of the Wrike dev portal and tell you what you should pay attention to.
During the redesign, we were able to:
- Create intuitive navigation.
- Create a grid for optimal display of content on desktop and mobile devices.
- Update the portal design in accordance with the current design system and create the missing components.
- Comply availability requirements AA level and introduce theming.
1. Intuitive navigation
We conducted a series of interviews with the main users of the portal – the backend developers and the user support team, which gave us feedback from external users.
During the interview, we found out that, in addition to technical problems with the notification and updating of information, the portal has problems with navigation: it is difficult for users to find important information – references and documentation. The difficulty was in reaching the sections located after the methods. For example, to find the BI Export section, the user had to look at all the methods at once; there was no way to collapse the section.
Navigation on the previous version of the portal
To optimize the structure of the portal, we distinguished the main sections and subsections, as well as separated technical content from informational. So, in the new portal, we identified 5 main sections: Introduction, API Documentation, API Reference, BI Export and Support, and secured the API Community section with a separate link at the bottom of the side panel so that the user can quickly get help if necessary.
Placing navigation in the sidebar helps users immediately see not only the main sections, but also subsections. And the ability to hide methods simplifies interaction with the panel. If necessary, the user can collapse the unnecessary section or, conversely, delve into the desired one. The logo, toggle and search (in development) remained in the top menu.
Updating the navigation on the portal (it was – it became)
To simplify the interaction, it is better for the user to show the structure of the portal with a nesting level no deeper than two. Additional features (for example, search) can be moved to the top menu. If users need authorization to use the portal, the login button can also be separated from the main navigation. This way you can quickly find the information you need and easily navigate between pages.
Navigation on the new portal
2. Grid for optimal display of content
The Wrike Dev Portal consists mainly of static pages with a variety of content. Tables and text blocks occupy the entire width of the grid, so the number of columns does not matter.
We paid special attention to the methods page. There are two ways to build this page:
- Divide the content part into two blocks: description and tables on the left, examples on the right.
- Make single block with content: examples are inside each method.
On the previous version of the portal, the first method was used.
Method page on the previous portal version: description and request on the left, and a slider with the answer and examples on the right
We analyzed the Wrike API methods and decided to use the second option. It allows you to save tables with their nesting in a readable form, as well as view the answer and example without switching the slider.
Method page on the new portal
It is important to provide for the grid behavior at different resolutions so that the portal is correctly displayed from the screen of a computer, laptop and tablet. No need to stretch the content part across the entire width of the screen, because reading text with a width of 2560 px is inconvenient. At the same time, breaking tables is also not worth it.
Create a fluid grid by setting the maximum and minimum width of the content area. Set the minimum indentation from the content part and make center alignment. The content will change in proportion to the width of the screen, but it will still be convenient to read text and tables.
It is also worth adding the ability to hide the sidebar so that you can increase the content area if necessary. This is very true when working on devices with a screen width of 1024 px.
The principle of the grid on the new portal
Most developers use devices with wide screens. But it is better to provide the ability to work with the portal and tablets. Open the sidebar on mobile devices over the content area. This will keep the information readable.
3. Updating the design of the portal in accordance with the current design system and creating the missing components
Portal API entities are different from standard website entities. I highlighted several components that required special attention from the design side.
HTTP methods (GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH) are one of the most important API entities. Depending on the type of action, the entity has a specific HTTP method. When designing HTTP methods, try to follow these guidelines.
- Assign each of the 9 existing HTTP methods a color identifier so that you can visually distinguish them without forcing the user to focus for a long time.
- For convenience, add a URL to the HTTP component of the method to make life easier for developers: they will not need to take additional steps to view this information.
- Provide the ability to see the query and example at the same time. In the new version of the Wrike portal API, examples are placed inside the method, and not hidden in the slider, as it was before.
- Do not place methods that relate to one entity on separate pages: in the old version of Query Tasks, Create Task, Modify Task – separate pages. Instead, separate the pages by entity: Contacts, Users, Tasks, etc. It will also simplify the interaction with the portal.
HTTP methods on the new portal
All requests sent to the server are presented in the form of tables with a large amount of data.
Table on the previous version of the portal
It is worth avoiding a pile of information. In the previous version, the mandatory parameter was indicated in the form of a badge with the inscription: this not only created visual noise, but also contradicted site accessibility requirements. In the new version, a separate Required column is highlighted for this parameter.
Table on the new portal
Try to make nesting the most obvious and indicate which parameter it refers to. In the previous version of the portal, only the description column was highlighted in color, despite the fact that the nesting related to the parameter as a whole.
Nesting on the previous version of the portal
On the new portal, chevron refers to the parameter itself and helps the user understand that the content is hidden inside.
It is worth noting that the columns of the nested table are better placed under the columns of the parent. This contributes to a faster perception of information.
It is important to keep the focus on the information highlighted. It is really difficult for the user to focus when working with a large amount of data. For visual convenience, when you hover the mouse over a line, it is worth highlighting it with color. The nested table is also better to highlight, while retaining the ability to select the row and inside it.
Nesting on the new portal
The example shows how to work with a specific method and what will be returned if the request is correct. The request is generated using CURL with the necessary data.
Examples need to be visually separated from the rest of the information and set a fixed height so that the scroll is inside the components, and not inside the page. This will save users from endless scrolling.
For comfortable work with the example, you can add the ability to copy to the buffer.
Examples on the new portal
4. Compliance and thematic requirements
Sites should be not only logical, convenient and beautiful, but also accessible for users with disabilities. As mentioned above, most portal components are compliant AA availability and inclusive design principles.
Contrast between plain text, headings, and graphic elements WCAG.
The site provides the possibility of tabulation, i.e. controllability and accessibility of the site for the keyboard.
Each graphic object has a description. So, for the buttons for copying information to the buffer, the text “Copy” is located next to the icon, when you click on the button, the text changes to “Copied CURL example”.
When an error is made in the application registration form, in addition to a text message and highlighting the input in red, a graphic symbol appears in the input field so that the user understands which field the error belongs to and could easily correct the entered value.
I would also like to highlight the provision of the user with a choice of interface themes. It has become a big advantage of the new portal for several reasons:
- This is a friendly solution that meets one of the principles of inclusive design – the principle of choice.
- Dark mode is the most common for developers.
- Dark mode adjusts the brightness of the screen to suit lighting conditions and reduces eye strain.
- Providing that with improved contrast makes the site accessible to people with impaired vision or color blindness.
Themed on the Wrike Dev Portal
To create a convenient dev-portal interface:
- Make navigation logical, convenient and understandable by separating technical content from informational.
- Immediately show the user the structure of the portal with a nesting level no deeper than two.
- Provide grid behavior at various resolutions for optimal content display.
- Pay attention to the design of methods by highlighting them in color.
- Get rid of visual noise in the form of icons in tables – the text works better than conventions.
- Keep focus on the highlighted information.
- Comply with accessibility requirements and inclusive design principles.
You can see how it turned out with us at Wrike dev portal.
I hope you learned more about API portals, and this article will help you design or redesign the API portal in your company. We, in turn, are not going to stop there, and we will improve the portal further.