Developer Portals: What Are They and Why Do You Need Them?

   In many companies, as the size of the organization grows, the complexity of the available infrastructure, services and APIs grows at an even faster rate.

With this growth, it becomes more difficult to know what resources exist and how you can take advantage of them. Plus, when you include external developers and third-party application developers, creating a central place for understanding and interacting with infra, service, and APIs will save time and ease onboarding.

This is where developer portals come into play. With developer portals, your organization can manage the complexity of the development ecosystem and make it easier for people to find what they need and get work done.

In this post, we’ll define developer portals, talk about their benefits, and look at how to successfully bring a developer portal into your organization.

What Is a Developer Portal?

First, let’s start with the basics. A developer portal provides a central place for developers to discover and use services.

To be clear, it’s not simply an API catalog. It comprises more than a list of API specs and documentation. It’s a central place for developers to go and learn about the systems that they work on and interact with. It provides self-service tools to get devs integrated quickly and easily. And it gives folks a place to go when they have questions.

 A developer portal provides a central place for developers to discover and use services.

Why Do You Need a Developer Portal?

To expand further on developer portals, let’s look at the “why.”

Depending on whether the developer portal is internal or external, it may tell us:

 
1. What services exist that fill my needs?
 
2. Why does a particular service exist? What problems does it solve?
 
3. How should a service or API be used?
 
4. Who owns this service?
 
5. How do I gain access to the APIs? How do I onboard?
 
6. Where do I find and how do I use the SDK?
 
7. How can I request help?
 
8. Where can I interact with the community?
 
9. What new features have been released?
 
10. What are the relevant SLAs or SLOs, and how does performance stack up?
 
11. What’s the service maturity or measured quality of the service?

For internal developer portals, these questions will increase transparency and reduce silos between engineering teams. There’s no need to coordinate through other teams or set up meetings if actionable and self-service guidance can be found in the portal.

Overall, these developer portals onboard developers, answer questions, and anticipate the developer’s needs when they integrate with your services and APIs.

Who Uses a Developer Portal?

Though we’ve focused mostly on developers, others also benefit from your developer portal. But let’s start with what these portals do for devs.

Developers

First, internal developers can easily identify and onboard to new APIs provided within the organization. They can also avoid recreating the same services that already exist but cannot be found or onboarded to easily. And, as your organization grows, this will help new devs onboard to the system context without needing as much assistance from devs that have been around for a while. And existing devs will benefit from a place to get the latest information about APIs, release notes, and changes to existing services.

Next, similar to new internal developers, external developers will experience better onboarding and get questions answered. But they also may be able to find other developers using the APIs through communities and message boards. The folks using your APIs need each other and will help each other if you create a space for them.

Supporting Roles

Support folks will use the portal to investigate problems, get the latest documentation and information, and use those to provide the support needed.

And developer advocates can combine their inside knowledge with the empathy they have for external developers to make sure the portals provide the information needed. They’ll be able to provide insight as to how easily consumable your services are.

Stakeholders

Outside of development, product managers can look at existing APIs and find new uses for them. Or they can connect the dots between different services that could come together to provide a novel product for your customers. The data org can access information regarding API usage and performance, perhaps finding new ways to use APIs through data analysis.

Finally, other stakeholders can visualize the performance and metrics of an API or service and make decisions about staffing, focus, and sunsetting.

Other uses of portals also exist, some of which may be specific to your organization.

Bringing a Developer Portal to Your Organization

As you read above, a developer portal can provide many benefits to your organization. However, you won’t be able to get all that from day one. To build a portal that’s suited to your org, you’ll need to identify your audience and their needs, determine what you will build and what you will buy, and how you’ll improve it over time.

Your Target Audience

For your developer portal, you’ll need to decide your target audience. Is this primarily for internal engineers? Or do you have a need to publish your APIs externally and provide support for external development teams? And of the various users of developer portals, which ones can you provide with benefits quickly through the use of a portal?

Based on the audience, determine which features will provide the most value. And once your portal is live, validate those assumptions through usage metrics.

To understand the potential, you must see the developer portal as more than a list of APIs or swagger docs. The portal guides its users and provides tools to utilize the lifecycle of the APIs, services, and infrastructure.

Build Vs. Buy

Next, let’s consider building or buying a developer portal. Usually, this will involve some combination of building, buying, and utilizing open-source software.

If you build, you could build from the bottom up, building just what you need for your organization. However, most features in a developer portal span diverse needs. Typically your use cases won’t vary too far from the portal consumer’s perspective.

Alternatively, consider using a developer portal platform, like Backstage. It will provide a solid base that you can build on top of.

However, either building from the ground up or even utilizing open-source software will require development resources. Therefore, you’ll end up taking developer time from working on your product differentiator and moving it into internal tooling.

Also, consider that you could start with a solution like OpsLevel.  This way you’ll have a developer portal and service catalog that you can easily expand for your growing needs without spending time on things that don’t improve your product.

Assess New Opportunities

As your organization grows and you bring on new engineers, onboarding and productivity can drop. The new engineers won’t have the institutional knowledge to get around, and they’ll rely on engineers that have been around to direct and guide them. Both types of engineers will slow down.

Instead, as your organization grows, develop self-service solutions. In effect, create a place where devs, both old and new, can find the most recent information around your changing and growing systems. Put these into your Developer Portal to centralize the knowledge they need.

Iterate

Finally, look at the portal as an expanding service with the potential to provide the right solutions for the right org. So, continually review what’s valuable and what’s not within the developer portal. Use analytics to assess which features of the portal aren’t being used. Investigate whether development teams are finding other solutions to those problems outside the portal. Perhaps you’re not meeting needs the way they could be met. For example, if teams across the org are re-creating features in the portal to meet their own needs, something is amiss.

A developer portal needs to improve over time and solve problems relevant to the engineering community using the portal.

Summary

Developer portals provide value to multiple roles both inside and outside of the organization. Before the complexity of your growing org makes onboarding and using your services too difficult, discover if developer portals can address those concerns.

Consider how OpsLevel can help simplify your journey. Request a demo today.

_{This post was written by Sylvia Fronczak. Sylvia is a software developer that has worked in various industries with various software methodologies. She’s currently focused on design practices that the whole team can own, understand, and evolve over time.}