What is API Developer Portal with Best Practices & Examples

What is the significance of a DevPortal?

So, why should a company invest time and money into enhancing its DevPortal? A good developer portal conveys the value of a platform and its services. It describes how it solves specific business challenges without using marketing/advertising hyperbole.

While API documentation is often associated with developer portals, a DevPortal is not just a place where developers access their API reference documentation. The DevPortal should allow all business stakeholders (technical or non-technical) to learn about and experience a platform.

In the next section, we will explore these characteristics.

What makes a good DevPortal?

The following are characteristics of an effective DevPortal.

Unifies solutions

While API documentation is an important aspect of a DevPortal, it is not the be-all and end-all. Developer portals ideally act as a central resource for all interfaces to a company’s products and services. They may not be limited to just APIs / services. Other interfaces include GUIs, no-code interfaces, and low-code interfaces like widgets for users without access to developer resources.

While REST APIs are a focus of developer portals, other kinds of APIs can be documented such as Internet of Things (IoT) APIs, voice assistant APIs, GraphQL APIs, or native library APIs. Oftentimes a company will have a range of services, not just a REST API. It is possible to see dozens of APIs of different types documented on a DevPortal. Other technical solutions made available on DevPortals besides APIs are client libraries or SDKs. Sometimes a DevPortal can also showcase solutions built by developers

Also Read: REST vs. SOAP: What is the difference?

Clear business model

The user should be able to understand the platform industry and a broad overview of the services it offers. Solutions should be categorized by area or specific business challenges they solve. The user should be able to develop a mental map of all solutions on offer and how they fit together in a unified platform.

How services relate to each other in the bigger context can be communicated through text, visual graphics, or the structure of the developer portal itself.

Up-front pricing

The customer should understand a platform’s pricing model very early on. The pricing structure should communicate how it solves particular problems and the differences between the pricing plans.

The DevPortal should answer questions like:

• How are the API products monetized (direct vs. indirect)?
• What are the differences between the available pricing plans? Are there plans for pay-as-you-go, self-service, or freemium?
• Are they any rate limiting restriction per pricing plan?

Pricing plans relate to the onboarding process because users are often allowed a limited number of features before they must pay. Transparent pricing facilitates the transition from a potential customer to an actual customer.

Content “layering”

Layered architecture is a concept borrowed from software development that can be applied to content organization.

Here is an example of how a DevPortal can be layered:

• The top layer of a developer portal would be the landing page the user understands the business model, an overview of services/solutions offered, and common use cases.
• The middle layer would be the solution categories that group solutions according to the business challenges they solve.
• The bottom layer would be the documentation for those solutions, including any getting-started tutorials and API references.

Of course, these are only examples. Other layers may be necessary depending on the business.

A layered architecture allows for consistency across solutions. The user learns what information to expect from each section.

Similar to the main landing page, each solution should have its landing page that communicates the value of the solution. A solution page provides quick access to the solution overview, use cases, onboarding details, getting started, and technical reference material.

Using a layered architecture that separates the different components of the platform allows for extensive use of linking. You can link to technical sections from business sections, and vice versa. For example, a business analyst that reads solution overviews may only want to view business information while also having the ability to learn more by clicking a link to the technical documentation. Linking also allows developers to jump to technical details rather than being stuck reading business material.

Consistent design

Design elements, when done correctly, go beyond aesthetics. Design elements promote usability and go together with the quality of the content. A well-designed developer portal has design elements that support the user journey as they discover, learn about, and interact with a platform.

An effective design reinforces the overall brand. A brand not only determines the aesthetic choice but also how the content is written. Documentation should be written using the same style and tone with consistency across all solutions.

Findability

How easily the user can discover the solution to their business challenge is the primary aim of a DevPortal. The process of finding information on a DevPortal should be frictionless.

The “findability” of information in the developer portal is determined by its structure and search/filtering capabilities. DevPortals should structure their documentation portals so users can easily see the range of solutions available. It should be easy to filter solutions by category to narrow down the list of possibilities and remove noise.

From within the API reference, you should be able to search and filter by resources, endpoints, parameters, and schemas.

Caters to non-technical users

SaaS companies also understand there are different ways to consume a technical product besides building an app that leverages a service from the ground up. For example, a platform may provide widgets you can easily add to your website with minimal coding. No-code or low-code solutions break down the barriers to who can experience the value of the technical product.

The best DevPortals have onboarding journeys for each competency level. For example, a technical user can build an app from scratch whereas a non-technical user can download a template to begin experimenting with.

Onboarding

The user onboarding process is usually a user’s first experience using a solution. If there is friction in the onboarding process, a prospective customer may give up before fully demoing the API. After setting up your account and retrieving credentials, the Get Started section walks the user through an end-to-end process of interacting with the solution, such as an API.

API Reference

An API reference is a concise and detailed guide read by developers to understand an API. Effective API reference pages allow developers to quickly locate information for resources, endpoints, fields, or schemas using a combination of searching and filtering.

A try-it-out feature provides a hands-on way of interacting with an API. The most advanced DevPortals automatically populate try-it-out widgets with a user’s credentials based on their account details.

Community

Community is often first-level support for troubleshooting issues. Many dev portals have community pages. Some companies use tools like Discord channels or public Slack channels to host discussions under different categories.

If a user can find an answer by posting a question to a message board, they do not need to contact support. If a company is involved in the community, it can log the issue as either a bug or documentation improvement.

Communities can go beyond just discussion forums. They can lead to small meetings or large conferences that promote a platform.

Updates

Regularly posting updates as a platform evolves is a signal for reliability and trustworthiness. Release notes, statutes, and changelogs are all examples of supplemental documentation that keep the user informed of the latest changes.

DevPortal Best Practices

There are many steps to building a DevPortal before any line of code is written. Assuming the business model is solid, developer experience (DX) design should be conducted to align all aspects of the portal to provide the best experience to users.

Clarify business model

The structure of the DevPortal should reflect the structure of the business and its solutions. The user will be lost if a DevPortal does not communicate the business structure well.

Keeping the portal up-to-date requires collaboration across the organization and will not succeed by relying on one team. All teams are responsible for keeping their domain up-to-date and responsive to feedback.

Conduct Developer Experience (DX) design

Developer portals are closely related to the concept of Developer experience (DX). Unlike normal User Experience design, DX is tailored to developers who use technical products often without a GUI like APIs, client libraries, or SDKs. Since there are no user interfaces, documentation must tell the developer how to interface with the product. Documentation to a large extent plays an important role in how a developer or other business stakeholder “experiences” a technical product.

In the same way, companies hire UX designers, they should hire DX designers to craft the experience of developers using the DevPortal. A DX “strategist” is a central role to manage the lifecycle of the developer portal. The DX strategist oversees changes to processes, standards, and tooling that flow out to individual solutions teams. This strategist ensures the design, aesthetics, structure, and content work together to create a pleasing experience for the developer.

The strategist creates the personas of the people visiting the portal and crafts user journeys to meet their needs. For example, there would ideally be separate onboarding user journeys for technical users and non-technical users.

Structure the portal

When establishing the information architecture, you must determine which information is required across all solutions. For example, each solution requires onboarding, use cases, and API reference in a particular order. If documentation is uniform across solutions, the DevPortal user knows what to expect.

A layered architecture, coupled with linking, will make navigating from the top layer (business details) to the bottom layer (technical details) easier, and vice versa.

Establish governance program

Many times, each solution is managed by a separate team. To provide a consistent experience across the portal, standards must be established that promote the consistent organization of content and writing guidelines.

Establishing a governance program requires collaboration to develop standards as well as buy-in from the separate business units to fully complete the program. Each team should be responsible for adhering to these standards and held accountable. A governance program should align language and tone, style and formatting, and organization of content from business material to API reference. Finally, a governance program should reinforce branding.

Reduce the learning curve through onboarding

After communicating the value of the business as a whole, the user should be immediately guided toward separate solution pages where they can try out APIs, services, client libraries, or SDKs. The front and center of these pages should be a link to onboarding procedures so they can experience the product as soon as possible.

For the Get Started tutorial, pick a simple use case that the user can follow to understand the solution from start to finish.

Properly document API reference

Are all the API components accurately documented? Is each resource documented? Are individual endpoints and schemas described fully? Does every field description state its purpose, the effect of chosen values, and interactions with other fields in the system? Are definitions for the same field standard across the spec? The content of the API reference should follow an API style guide that determines standards for all components of the API. Following a style guide ensures consistent and complete documentation across the API reference. Without accurate and detailed reference information, all the flashy features are useless.

Documenting technical reference information is often the first step to improving overall documentation because the technical information must be solid before writing tutorials.

Configure search / filtering

A DevPortal can have dozens of pages corresponding to separate solutions. Along with a clear site structure, having a robust search can improve discoverability so the user can find the solution that solves their particular business issue.

There should be an API Explorer where the user should be able to search and filter a list of solutions offered.

It is important to have a robust search in API reference docs. The search bar on an API reference should allow for a granular search of all components making up the API.

Establish community

From early on, you should think of ways to foster and grow a community around your business’s solutions. This is both a long-term strategy for support and also for the adoption of your products.

Other subtler forms of community are asking developers to sign up for newsletters that keep the communication line open.

Initiate a feedback loop

There should be many opportunities on a DevPortal for a user to provide feedback. For example, each API reference section provides a rating mechanism with the option to provide free-form feedback.

Another source of feedback is community. A community actively using a product that posts is a source of feedback without even having to ask for it.

Provide case studies and references

Case studies are convincing when they are coupled with testimonials of clients that use the product. Case studies can be common business challenges and how they are solved using a platform. A user may relate to a case study and immediately see how they can use the tool to accomplish a certain task or solve a problem that someone else experienced.

Also, check out our blog on API documentation checklist

Regularly post updates and statuses

Regularly posting updates as a platform evolves is a signal for reliability and trustworthiness.

Also Read: What is Open API? Advantages, Disadvantages & Examples

Best DevPortals

The following are the best DevPortals by category.

Best API Reference: Stripe

Stripe is a payments processing platform with a well-designed and intuitive API reference.

API reference docs must allow developers to locate the information they need quickly amongst the sea of technical details.

Stripe is a one-page website that allows you to quickly navigate to different sections either by clicking the left nav links, scrolling down the page, or performing a search.

Some of Stripe’s API reference features include:

• Collapsible content – Almost all content is collapsible, including field descriptions, tables, schemas, etc. This way you can focus on the information you need without excess clutter.
• Switchable programming languages – You can change the programming language of code samples globally with one button. In addition, you can also easily copy code samples by clicking a copy-to-clipboard button.
• Developer-friendly dark mode – This is a great feature for developers who prefer a dark background that looks like a code editor.
• Extensive Linking – Whenever an in-depth explanation is required, the API reference provides a link to the conceptual documentation for background information and tutorials.
• Multiple feedback points – You can provide feedback for each section, including writing free-form text after giving a rating.
• Advanced search and filtering – Stripe’s advanced search lets you field on almost all components of OpenAPI.

Best findability: Visa

The Visa Developer Platform lets you leverage the power of the Visa network using APIs.

What makes this platform stand out is how easy it is to filter the available APIs and services to find the one you need. From their Product Browser, you can filter the list of APIs by several categories. Filtering allows you to quickly locate the APIs that solve your particular business challenge.

In the filtered list, each API “card” contains a short description of the service, followed by links to the Overview or Docs pages for the API. The Overview contains general business information, whereas Docs contain the API reference. You can then locate the documentation you need quickly based on whether you need to onboard or wish to view technical references.

In addition, you can locate use cases that apply to your situation from the Use Cases page with testimonials and case studies.

Also Read: Internal vs. External APIs – Does it Matter?

Best coding tutorials: Fiserv

Fiserv’s developer portal shines when it comes to step-by-step examples of how to implement Fiserv’s APIs.

“Recipes” are tutorials for different use cases with code samples in various languages. Each recipe walks you through the process of completing a specific task, and each step in the process has annotations that provide more context.

The recipes shine when accessed from within the main documentation. The main documentation links to specific recipes whenever a step-by-step guide is necessary. This integration of code samples within documentation makes Fiserv’s platform very use-case driven.

Best for non-technical users: platformOS

platformOS is a development “platform as a service” that emphasizes performance, reliability, flexibility, security, and scalability with many use cases.

platformOS is one of the most accessible platforms because it caters to users of all technical levels. It classifies 3 different types of users: non-technical users, semi-technical users, and technical users. Each user type has its onboarding journey.

• Non-technical users can click 1-click install to register an account and follow an easy setup wizard that creates a demo blog site.
• Semi-technical users can click the Sandbox link to clone a demo site from GitHub. They can then follow the Hello, World! guide to understanding the basics for sending requests and reading responses.
• Technical users can dive right in by clicking Build your first App to create an app using the platformOS platform. They can follow the documentation to set up their dev environment and then deploy and test their app.

platformOS allows non-technical users to experience the platform while providing a fast route for technical users to build an app from the ground up.