When we think of Application Programming Interfaces — APIs — we may not immediately pair them with User Interface design. Implemented as a background tool, APIs are largely in the hands of developers, and technical documentation has a natural reputation of being elusive for laymen.

However, this mindset is not sustainable. User Interface (UI) is the graphical component for your API — a powerful front-face to your service that should stand as a beautiful product display. Whereas good design establishes branding and trust, poor design can have quickly detrimental effects.

One study found that visitors assess the visual appeal of a site within 50 milliseconds. Missouri University research similarly concluded that users form an impression of a web site within two tenths of a second, and that it takes about “2.6 seconds for a user’s eyes to land on that area of a website that most influences their first impression.”

As ‘API’ extends beyond developer-only conversation, peaking the interest of entrepreneur, web designer, or CEO, many parties view the developer portal as a location where API providers provide an introduction of their service to the world. This site will immediately be critiqued as would any other product page. As this is the case, it’s a great idea to arm yourself with excellent design. In this piece, we explore quality site architecture, interaction, layout, and branding that can make your API homepage feel current and easily understandable for all users.

Design is Not About Making Things Pretty

As a first point of contact, the main goals of an API developer portal are to attract new users and onboard to ‘Hello World.’ In order to achieve this, a developer center must be usable, producing actual code and maintaining a dialogue with the visitor. According to Kemie Guaida, a designer at the API consulting firm Dopter, successfully designed API portals are more than visually appealing, they are:

• Understandable: parameters are easily understood
• Usable: interactive with intuitive architecture
• Attractive: creates a pleasant experience
• Branded: consistently reflects brand

Supplying technical information is an essential developer experience, but Guaida reminds us that all kinds of users may be visiting the developer portal, so learnability and presentation should be accentuated. Now, we’ll cover three core tenants of design and how they apply to APIs, and showcase examples of some nicely designed API developer portals that any developer program can model.

3 Elements of Software Design

Here are some practical points aimed toward non-designers who may not own Photoshop or Illustrator. Whether we’re talking about an interactive web app or mobile app screen, good software design is a seamless bridge between human and machine. Three principles to keep in mind throughout the entire process of software design are:

1. Information Architecture
2. User Interface
3. Visual Design

1: Information Architecture

When designing site-wide information architecture, it is important to note the priority of what information the site visitor needs to know. One must consider what information developers immediately desire to see, and what resources visitors with varying levels of experience will require.

Providing detailed documentation is a must for a technical audience, and your non-technical audience will require information on licensing agreements, an often underprivileged aspect. Your structure should accordingly group relevant information into categories that are easily understandable and easy to find. It’s a good idea to order sections from the broad to specific, making sure that you have clear paths to the information, and a good search by keyword or topic option available.

As an example, take the MailChimp API portal. It prioritizes highly pertinent information with a reminder of v3.0 version release and deprecation notice. It also does a good job of structuring information in order of beginner to advance, ordering sections from Getting started —> How-Tos—> Downloads and API wrappers —> Actual API Documentation. Links that may be irrelevant to a bulk of site visitors, like Partner APIs, or MailChimp’s Mandrill service, are still included yet listed toward the bottom in accordance with priority.

“A good interface should be clear for any type of user. A beginner should be able to come into your portal and understand it the same as a super technical user”

MailChimp uses good site architecture to order information

2: User Interface

The user interface is where the human interacts with the information presented before them. A designer must jump into the psychology of the user, considering that upon visiting a site for the first time, a user needs to know what I can do and how can I do it. To immediately satiate these questions, design with:

• Consistency: make things look and behave the same way. If you have a search form, for example, have it always placed in the same place on the page. Follow conventions and especially the rules you create.
• Clarity: text is part of the interface. When naming parameters, use terminology that users will understand. Consider your overall tone — will your documentation be dry and to the point, or light and fun? Choose a tone and be consistent throughout your API documentation.

To plan a UI flow one must sketch a wireframe to consider the key components of each page. This can first be done drawing boxes and dummy text on pen and paper or whiteboard. Interactive wireframes or mockups can be generated using software like Balsamiq, Axure, InDesign, Briefs, HTML prototypes, or the Bootstrap framework.

Using available software, it’s relatively easy to wireframe a semi-functional prototype. To have an idea of how things are really working, encourage user tests to gain valuable insights and feedback on the dev portal before launch.

Bold, stately fonts accentuate Twilio’s chic dev center UI

3: Visual Design

Visual design is arguably the most obvious to any reader. Visuals and graphics are about look and feel, a more subjective experience on how the user perceives the interface. Is it light, airy, technological, or classical? This all has to do with your brand. Relevant methods used in visual design include:

• Layout: how are things placed in relation to one another.
• Hierarchy: use coloring, font sizing, or font type to make important titles stand out, opposed to body text. For API portals with much information and functionality, everything cannot be flat, as that will only increase confusion.
• Grouping: group things that are similar in functionality or content. Consistent shapes, colors, or white space manipulate the brain to automatically relate things as a unit.
• Aesthetics: though API documentation should prioritize legibility and clarity, colors, type-faces, grids, and more should still be considered and made consistent with company branding.
• Grids: have a grid system using grouping, and create units to place around page.

For an example of superb visual design, consider the Campaign Monitors API page. The page uses subtle graphic icons, a large title, and a light blue hue highlighting the navigation bar. The use of a grid with plenty of white space makes the page look orderly, well structured, and professional.

Campaign Monitors API page exhibits an appealing style and structure

Process: How do I Get This Design?

API providers likely have internal designers and developers that can implement great looking API portals. But remember that you don’t have to reinvent the wheel — some API management services and specification formats already supply interactive API documentation. Using programs that create documentation automatically may inhibit customization, so choose solutions that allow for unique CSS inputs to match your branding. Perhaps still, what the API space needs is better API documentation and UI deployment options.

Conclusion: Final Checklist

Different design styles can be used for APIs targeting different audiences. Enterprise design may use stable, black and white text, whereas MailChimp’s branding is younger, brighter, reflecting their startup clientele. Regardless, a quality user interface is universal for any type of visitor.

As a review, when designing API portals, consider the following main items:

• Have right information and right structure. Developer portal is more than reference documentation, and should be understandable for all types of users.
• Is it easy to interact with? Perform user testing on your API portal, see how easy it is to navigate.
• Ensure it reflects brand. People are more likely to be recurring users of an interface that is visually appealing and consistent with the company’s brand.

API portal design is about engaging users with your API. It’s about engaging with the brand, and producing excitement to consume your API as an asset in their productivity toolbox. In the end, increasing developer experience with beautiful UI design begins an organic conversation that improves the chance of overall success with recurring developer users.

“An API that has happy users is an API that will thrive. It is an API with users that will not only use it, but will talk about it, and recommend it”