Your developer portal is a powerful channel for communicating your API details. The ability to connect with developers is so valuable that an effective developer portal is often a predictor of overall success. And building a quality developer portal is easy if you follow some general best practices.

Below, we’ll look at a handful of best practices for creating quality developer portals! We’ve organized this list into methods that support the human, facilitate understanding, and provide adequate tooling. While this piece is not exhaustive of all best practices, the advice here should help establish your offering in the upper echelon of developer portals.

Supporting the Human

1. Implement and Communicate Design Standards

Before discussing the portal itself, we should first discuss the underlying API. The best first step to making an effective portal is designing an API that’s sensible and easily understandable.

First and foremost, employ naming conventions and ensure that these conventions are consistent across all documentation, SDKs, onboarding systems, and communication materials. Doing so will go a long way towards ensuring the resultant materials and the portal which collects them will be high quality.

Secondly, ensure that this design standard is reflected in the systems too. The API structure should be well-designed, and data formats should be consistent across responses. Look at your naming conventions and ensure they are logical in context with other components. Adopting style guides can help ensure these standards are documented and understood throughout the organization.

2. Design for People

API developers should always remember that their end user is ultimately a human. Even though APIs enable programmatic connections, the user who sets up the integration is human. As such, they need clear expectations, understandings, and needs that must be considered while designing the portal.

Consider the structure of your portal. Does it flow from one place to another in a sensible way? Is it understandable at a glance, or does it require a lot of inspection to find something simple, like a method’s endpoint? Can people understand how to access different parts of the portal and actually use them?

Even beyond the structure, developers should consider the design aesthetic. Is the portal garish? Is it overly complicated and hard to parse through? Are you presenting too much information at once, or is the design too spartan? Designing for people requires an understanding of user interface (UI) design and is part of ensuring quality developer experiences.

3. Provide Intuitive Documentation

APIs live and die by their documentation, which is just as true for developer portals. A good portal should surface documentation to the user and answer common questions. This requires a good deal of thought as to how to form that documentation.

Providing thorough and clear documentation that surfaces the underlying data structures is vital. Notably, adequate documentation isn’t just textual materials. Good documentation should include a variety of SDK reference guides, API endpoint maps, and more.

What’s equally important is providing intuitive documentation that’s easy to navigate. The user should be able to find the answer to their question in as few steps as possible. For instance, if a user needs to know about authentication, they shouldn’t need to go through a complex, labyrinthine set of menus and links. Instead, they should be able to find this answer through a simple search.

Facilitating Understanding

4. Consider the Onboarding Experience

A user’s first impression can be a dealbreaker. Users are coming to your portal for very specific purposes. But if your portal features a deep dive into the history of the product, rather than answering common questions, you are rejecting those use cases. What if a user is coming to find tooling to help them log errors or discover issues in their implementation? Not including relevant material in navigation will nullify that use case.

Ultimately, the developer onboarding experience should be considered and supported. Ensuring that the user can easily find relevant materials, generate API keys, and discover new functionality must all be facilitated by the onboarding experience of the portal itself.

One way to consider this best practice is to assume that someone coming to your portal has absolutely no experience with the product. How do you get this user to the state where they can implement what they are seeking to implement? This can be a guiding light to make the onboarding experience as effective as possible.

5. Communicate Versioning and Change Management

Your portal should always ensure that the user has a firm understanding of what they’re actually looking at. A developer portal may catalog a number of versions or changes, some of which may be compatible and some may not. A big step towards ensuring the value of an API portal is properly communicating versioning and change management.

It’s important to note that the developer portal is one of the best tools for collecting changelogs and centralizing the information relevant to new features, updates, bugs, roadmaps, and so forth. As such, it should be considered a vital piece of your collective communication planning.

6. Provide Sample Code and Implementations

A good developer portal should not just explain how things work but should also show them in practice. Providing sample code and implementations is the best way to do that. Portals should provide, at the bare minimum, basic code examples and implementations that help the user get from zero to start in as little time as possible.

To make for a genuinely effective developer portal, you can go one step further and provide customizable or live code examples. In such a system, the user can insert endpoints, write their own code, or even choose from a list of stock code to manipulate, change, and experiment. This is a low-stakes way of enhancing developer user experience within your system.

What’s important here is to remember that despite being machine-readable, this code is still understandable by humans. Accordingly, code should be concise, well-documented, and easy to parse. Additional context and content can, of course, be provided through various means, but everything in this section should be centered upon creating a system by which the user can see firsthand how the code should look and what the ultimate function should be.

Providing Adequate Tooling

7. Give Them the Tools!

A good developer portal is much more than documentation. Developer portals are your number one opportunity to tie together your documentation and communication with a set of live exercises and tools. The developer portal should exist as a “one-stop shop” for your users’ needs.

Various tools could help here. Firstly, you should provide ample tooling for those getting started. Tools such as request and response validation, sandbox testing, and more can help your users get from zero to go in no time flat. Secondly, tooling for ongoing functionality should be highlighted. Error identification, routing, and efficiency of endpoint service could be tested using tools provided by the developer portal. Other tools could assist in logging, analytics, and debugging. These would help support the user from a beginner state through a more complete and expertly implemented solution.

Developer portal tools can help level up the developer experience and present valuable data for internal purposes. Finding the most common points of inefficiency or the most common failed implementations can help you craft better documentation. Tracking the most used tools could increase visibility and expose weaknesses, guiding the lifecycle of your product.

8. Consider Automation

For creators who are facing the cost of a developer portal with a certain amount of trepidation, there are many systems that can deploy effective developer portals and portal elements with little development cost. Some examples include:

• The solution by Microsoft Azure can take API specifications and schema and deploy a platform that is quite a good start.
• Swagger UI can form the backbone of a great portal, setting up a documentation-rich jumping-off point for other automated systems.
• The OpenAPIHub Portal Generator is another excellent example of a fully-automated portal creation solution.

Good Example Developer Portals

In the past, we’ve highlighted some examples of quality API developer portals. Let’s review some of the best examples:

• The Visa developer portal provides helpful developer onboarding and tools. The Quick Start Guide for Developers is a particularly good example, providing a great sandbox, tons of use cases, and a robust code explorer to get users going immediately.
• The Spotify developer portal is an excellent example of an intuitive portal built for humans. Developers can easily guide themselves through the platform to understand how the Spotify developer tools function.
• The Discord documentation presents an authoritative resource that gives you literally every piece of information you would want from Discord as a product. This developer portal is an excellent example of how deep documentation can get.

The Developer Portal: A One-Stop Shop

The biggest danger when creating a developer portal is considering it secondary to the API itself. The simple fact is that the developer portal is the best way to communicate a variety of details to your users. As such, it presents the best opportunity to create a one-stop shop that informs, levels up, and supports your users across the board.

What do you think of these best practices? Did we miss anything important? Let us know in the comments below!