What Makes a Great API Developer Portal

What is a Developer Portal?

A developer portal is an interface used to display APIs, SDKs, or microservices to developers. They are websites used as bridges between services provided by a company and its users. This is a way to create a self-service experience for developers while offering a catalog of said services to them.

Developer portals usually support access management, provide documentation and facilitate integration work. Their purpose is twofold: to clearly display all the services a company wants to put upfront and to facilitate their usage.

For example:

• Inside a company, a developer portal can help centralize the numerous services used by teams across the organization, thereby improving productivity and helping manage usage and access.
• For external usage, the developer portal is a dual asset in that it shows the value of the services provided by a company while increasing their adoption.

But to make it fully effective, the developer needs key features that will truly help users discover, understand and consume services.

Note: in this post, we will concentrate on API developer portals.

Key Features of a Good API Developer Portal

Addresses all profiles

Despite the name, the developer portal shouldn’t be made just for developers. It also acts as a showcase for a company’s APIs, and therefore needs to be fully comprehensible for other profiles, not least products and growth teams. The need to address different profiles works at two levels:

• If you use a turnkey solution, make sure it will offer a crisp catalog experience for your APIs, with plenty of room to elaborate on the services offered by the APIs and the value they provide. The way key features we’ll see later are assembled is equally important. UI experience matters.
• At your level, use a product approach for your APIs. Short, clear sentences that go straight to the point help all profiles, not just developers, to understand where the value lies. Monetized or not, use the same approach, and always ask yourself the question: could non-technical profiles in your organization understand the service?

Clear use cases

On par with addressing all profiles, the APIs displayed on the developer portal can adopt a use case approach that has the benefit of helping the user know how services provided by the API can help them.

See this as reverse thinking: not showcasing the API is not the main asset, but the services it provides. This method can help organizations with large APIs adopt a segmented view adapted to the use cases of their customers.

Clear monetization models

The developer portal is the perfect vehicle for exposing APIs to the world. And the opportunity to monetize them. What is essential here is to establish clear monetization models. We developed how to choose the best monetization model here.

Many companies used to bundle APIs with other features, often in higher pricing plans. It is now common to have separate pricing for APIs or to include it in smaller pricing tiers, with rate limit policies.

Transparent pricing on the developer portal includes:

• The monetization model, between pay-as-you-go, subscription, tiered, freemium…
• The rate limits for each plan or tier,
• The unit used to bill, as the API call may not be the most relevant for every business model.

User-friendly design and branding

The developer portal is the extension of a company’s identity and as such, as important as the marketing website because t is through the portal that users will start consuming APIs. If the developer portal was once seen as a simple technical platform, it is now an asset and needs to be treated as such.

This is why branding is important too: featuring your logo and colors, keeping a unified tone for your documentation… Every detail plays a part.

Communication

Since the developer portal is the space where APIs are shared with the world, it is natural to include a way to communicate with the users. There are several ways to establish a trust bond with users:

• Automatic emails come first They automatically inform the user about events linked to their usage. They must be included as they will only be triggered at key moments. It is important to pace these emails, finding a balance between not enough and too many.
• User contact information can be used for direct contact. This is more of a hands-on approach, but when noticing an important error rate or a usage drop, sending an email to ask if everything’s okay can be a nice touch, especially if the user is also a customer.
• Integrating a chat tool into the developer portal is another way to keep a close relationship with users. They can instantly send feedback or require support. This feature can also be monetized, by only being offered to the biggest users or as part of the higher pricing plans.

Each layer of communication is important and plays a part in building a stronger link with users, thereby increasing retention in the longer term.

Analytics and logs

Analytics and logs are also critical. Their function is to assess the usage of the APIs, improve adoption and grow usage. Let’s see how:

• Logs help assess the usage of the APIs, and most importantly, are quick to take action when a user has too many errors. Good logs can be filtered and exported, thus providing accessible sets of data to help debug any issue with any user. This data can also help determine error patterns, which are often the result of patchy API documentation.
• Analytics can boost adoption. This is a critical step during which APIs are frequently abandoned. The Time to first call is one metric to consider, paired with the adoption rate and usage growth. Taken together, those three metrics can help establish a retention strategy that will be delivered through behavioral or manual emails on the marketing and sales side, and on product and documentation improvement on the product and engineering side.

API Documentation

We’re short on synonyms to emphasize the “essentialness” of features, but this one is especially important. There is plenty of content on the Internet explaining how to improve API documentation, but this subject remains the butt of many developers’ jokes. A great developer portal can address those pain points with a few simple additions.

Our report about the top API developer portals singles out some of them. Here are the most common among the top-performing portals:

• Sample examples are essential to explain the structure of the call and the type of response given by each endpoint**.**
• API reference gives a clear view of the endpoints of the API and descriptions that help understand their purpose.
• Errors descriptions, as we saw earlier, help users understand the reasons why they don’t have 200 responses.
• Quickstart delivers the value of the API to new users by helping them perform their first call.
• Code snippets eliminate the pain of having to rewrite the code in another language.
• Rate limits are like error descriptions, the clearer they are, the better the chances of seeing user error rate improve.
• “Try it out” is like an upgraded API reference. Users can make a call and play with query parameters. An excellent way to display the value behind APIs.

‍

Examples of Great API Developer Portals

Stripe

A benchmark in the field, Stripe was one of the first companies to truly understand the value of an enhanced developer experience. Stripe provides payment solutions through APIs.

What makes it great: a developer portal for every profile

• Unified branding and user-friendly design

There is no real discrepancy between its marketing website and its portal,making it easy to understand the value of the product. Every profile can quickly get how using Stripe can help, with documentation that skips too technical wording for a straightforward approach.

Every page displays a clear, detailed summary of its content, and paragraphs are linked with the relevant related content.

• Complete documentation

Its API documentation includes code snippets, a preview, and an integration workflow. The only thing it lacks is a “Try it out” option.

• Clear use cases

Each product is displayed in a way that helps the user understand its purpose: Billing, Payments, or Connect. The menu is clear and indicates each step of the payment process. “Quickstart” options provide users with short code samples that deliver the use case.

Twilio

Twilio is the other benchmark in the field. Its communication APIs gained traction in part because they are easy to implement. The developer portal is geared towards facilitating adoption and quickly delivering the APIs’ added value.

What makes it great: facilitates the first call to show the value of APIs

• Product approach of the APIs

The portal is organised according to Twilio’s products, each of which is summed up in a short, simple name. Call-to-action buttons urge the user to test the API and everything is made to facilitate the first call. Twilio incorporated several marketing tactics in their dev portal, such as numerous call-to-action.

• Quickstart

The numerous “Quickstart” options are also part of this same strategy to minimize time to first call. Twilio obviously gets that adoption is a matter of simplicity and getting the developer to make that first call is half the battle. Each Quickstart offers a range of coding languages and delivers a clearly established use case.

Mapbox

Mapbox is an API-first company providing location data. What is interesting about its developer portal is the level of detail given to the discoverability and tutorials of the APIs. Along with the documentation, playgrounds help the user discover potential use cases for Mapbox products, and tutorials support them through their first steps.

What makes it great: discoverability through playgrounds and tutorials

• Playgrounds to test and try functionalities

For each API, a playground enables the user to test functionalities in real-time without coding. A window produces the URL request and subsequent response, giving the user an idea of how the API works. Aside from the documentation they provide, the playgrounds illustrate the use cases of each API and thereby act as a discoverability tool. They therefore help improve adoption and extend potential usage.

• Tutorials adapted to a wide range of profiles

Specific use cases are also available in the form of tutorials. The tutorials can be found by selecting the product and the required coding language. What’s interesting here is that the user can choose from varying levels of difficulty. This helps the user navigate, adapt, and progress by supporting their skills and providing them with baselines to use for further personalization

Blobr

Blobr provides a white-label developer portal combining most of the features previously mentioned in just a couple of minutes. It can be used as a branded developer portal uniquely for the purpose of sharing APIs or for monetizing them as well.

What makes it different: discoverability and all-in-one portal

• Clear use cases and discoverability

A product catalog features APIs in the form of products: one API can be divided into several use cases that will have different values. This has the advantage of facilitating discoverability while displaying clear monetization models.

• Quick implementation and workflows

Each product has its own implementation guide, in the form of workflows. Instead of having a look through the whole API documentation, users just have to follow the steps offered by the provider. Like in “Quickstarts” on other developer portals, users can test endpoints and easily implement the API product using code samples.

• All-in-one place for users

From API key management to payments, Blobr provides a single place for users to test, implement and manage their usage of APIs. The developer portal and the dashboard are in the same place.

Final words

There is not one perfect developer portal, but several, depending on your goals. But every developer portal needs to address all profiles and have clear use cases. A user-friendly design and branding, communication tools, analytics and logs, and comprehensive API documentation are also key to improving adoption. One could say that “developer portal” is too restrictive a term to designate a platform that no longer serves just as a technical website, but as a crucial asset to help grow your business and your API usage. These examples can help you reach a broader audience and complete your marketing website with an operational portal.

‍

‍