What is an internal developer portal and why do you need one?

An internal developer portal is a central information hub about API products, documentation, and microservices. Read to know how your developer team can use it.

August 3, 2022

Developer portals are usually considered external, i.e., a repository of information and resources for developers who are using another company’s APIs. These portals give API teams access to support in the form of information concerning the APIs. Companies feature developer portals (dev portals) and forums on their websites, and these are spaces where you can try out their new API products and benefit from a range of features and resources. Developers can get different response shapes, look at the API documentation, and get support when needed.

Today, a different kind of developer portal has surfaced. The inner developer portal is similar to the external developer portal in functionality but aims to address internal doubts. External developers have access to all the information they need in a single place. Why can the same not hold for developers within a company? In this regard, an internal developer portal acts as a storehouse of information for the developers in your company. Functionally, both kinds of portals are similar, only differing depending upon the kind of information and resources their target audiences would benefit most from.

In this article, we do a deep dive into internal developer portals. Understanding what they have to offer is essential to making an informed decision in alignment with your developers’ needs.

What is a developer portal?

A developer portal is a centralized repository that stores and displays all the relevant information concerning the software a team is building. Having the data in one place allows developers and managers to build a system that helps them keep track of the software ecosystem, get notifications on changes, and visualize related information. Such a portal also makes it easy to keep an eye on various aspects of the software development process, such as the microservices and how they are connected, ownership status, dependencies, resources, and more.

An internal developer portal is generally composed of a few different tools. Each of them has a distinct function and is equally important in providing developers with a comprehensive picture of what they are building.

Service Catalog

The first part of a developer portal is a service catalog. Its primary objective is to give developers and managers a lay of the land so that they are clear on what exactly they have in their systems at any given point. This includes everything from what projects and services are currently running or stored in the company and what each of them does to tagging them with specific metadata in a structured format. It also includes information on ownership, on-call, and runbooks, as well as documentation. By offering an extensive overview, the service catalog helps developers identify the baseline that they are at. Only with adequate data in this regard, i.e., by knowing what exists, can they reflect on what needs to change or improve and take the appropriate actions for optimization.

Project Generation Tool

A developer portal usually also has a project generation tool, like Cortex’s Scaffolder. This gives developers the ability to not just track what services they have but also to spin up new services from within the portal itself. This way, the developer portal operates the services from the moment of their creation. This is important because, to give developers a unified experience, it is best to start from the moment a project is conceived. When they can create new services and subsequently keep track of the same services in the same place, you are maximizing the potential of a developer portal. 

As a result, the developer portal is able to handle everything from getting information about on-call schedules and triggering incidents to deploying things and dealing with incident management. Following this, all the aspects of actual production use of a particular service belong in the developer portal as well.

Customized Tools

At this stage, the developer portal starts to fork, depending on your company’s use cases. You might use a developer portal to drive the adoption of best practices and standards, or you might be more interested in using it to build customizable abstractions. For some, the priority is to drive behavior and incentivize people to, for example, use the company’s new Kubernetes platform. Increasingly, we are seeing companies using developer platforms to inculcate these new behaviors in developers and tailor the architecture of the portals to suit their specifications. 

Why do you need a developer portal?

If it is not immediately clear why having a developer portal is worth the time and effort it might take to put it together, here is a list of reasons that highlight the benefits of incorporating this in the software development processes at your company.

A unified experience

There are multiple reasons to set up a developer portal for your team. The first is to give your developers a unified experience of a developer community for all the different tasks that are part of the development lifecycle. This includes foundational activities such as spinning up new services and operating those services in real-time. Additionally, a developer portal is also designed to go one step further and incorporate tasks like API management, documenting services, running actions on them, deploying pieces of software, and rolling them back if needed.

By providing a comprehensive end-to-end experience, you make it easier for everyone to be on the same page and have eyes on the entire lifecycle. Built on the concept of self-service, a development portal also speeds up service creation and deployment processes, among others. Without a development portal, not only do you run the risk of losing things but it also becomes difficult for developers to communicate and collaborate effectively.

Clarity and onboarding

Software development is a complex process, especially when it involves architecting a variety of microservices and assembling them to build an application. With the assortment of tools put to use to develop software today, the development lifecycle is more or less scattered across these tools. As a result, the developer experience is fragmented and discordant.

This is made more complicated by the fact that things are constantly changing in the development environment. Not only that, but every company also has its own set of tools they use and practices they follow. The lack of clarity is palpable to the point that developers may be dealing with obstacles that could be easily avoided. For example, it becomes difficult to onboard and explain to a new team member how work is done within the team, whether they recently joined the company or have switched over from another team.

In this context, a developer portal pulls everything into a single place to give developers a single, unified, high-quality software development experience. They can continue to use the tools they prefer and follow certain best practices without having to worry about integrations or difficulties in communication with fellow team members or engineering leadership.


A developer portal simplifies documentation practices as well as the process of looking up any docs. Its centralized nature ensures that developers need not embark on a wild goose chase every time they need to look up something specific. Clear and easy-to-find documentation also does away with the potential for discrepancies in the information.

Improved developer experience

Many companies today are brainstorming ways to deliver a high-quality developer experience to their teams. This is because a better developer experience leads to increased engagement and velocity.

Having a developer portal improves your developer experience. The developers are faced with less confusion and unnecessary roadblocks as they go about their work. Developers who have more clarity and visibility into what is going on at various levels in the team are more likely to be efficient and happier. These portals also help developers cement their CI/CD pipelines. With these pipelines in place, developers can deploy frequently and with ease.

A developer portal is one of the easiest steps you can take to improve your developer experience aside from taking measures like investing in platform tooling. It is one of the smarter investments to make for enhancing the developer experience.

Establishing best practices

Finally, the developer portal is also instrumental in establishing good development practices in your company. Developers are often talking about abstractions and hiding software complexity from users. So why are developers not privy to the same experience?

Consistency is key to simplifying and streamlining processes in your teams. With the inclusion of certain best practices in the team member’s workflows, it is easier for developers to connect various microservices as well as collaborate with each other. One of the core ideas behind setting up a developer portal is to help you prioritize efficiency and bring standardization across your entire organization in addition to increasing visibility and improving velocity.

Those are some of the key components of why you would want a developer portal. It catalyzes the improvement of your team’s daily work life as well as contributes to better management of the product building process.

What are some best practices to follow?

Developer portals, like any other tool or aid, need to be configured keeping in mind certain ideas. These best practices are guidelines, and ultimately it is for you to decide what will work best for your teams.

  • Your development portal should respond to the operational and developmental needs of your company and its stakeholders. Additionally, because these business needs change with time, it is important that your portal reflects that and is modified such that it can effectively help your developers.
  • Self-service is an essential component of a developer portal. The portal should encourage developers to work autonomously in addition to streamlining and automating basic processes for them. When meaningfully structured data and relevant resources are made available to developers through automation, the team does not need to spend time and energy locating them and can instead focus on making active contributions to building or improving the software.
  • API portals are a fairly common use case for developer portals. In a sense, developer portals are also a source of truth as they compile information about your team and their work. So it makes sense to make use of APIs to fetch data about the services you have and related metadata. Doing so will allow API developers to also update the developer portal using APIs and make it easier to have API documentation and tutorials in the portal for each service.

How can you set up a developer portal for your team?

Because the developer portal is meant to contain a wealth of information, it may seem like the process of putting one together will be long and arduous. There are various options available on the market, depending on your company’s needs and the amount of bandwidth you have to set it up.

Time and effort permitting, you can build one from scratch internally. The biggest advantages to doing so are the levels of customizability and flexibility. That said, this is a demanding process and may take months to materialize.

There are also certain open-source portals that have the basics in place before you can modify them to use in your company. Backstage is a popular option that takes a build-it-yourself approach. It comes with a service catalog, but aside from that, you are left to your own devices to piece together a set of plug-ins. As a result, you also have a fair degree of flexibility when using Backstage, and you can build any kind of developer portal you want based on your needs.

Finally, you also have solutions that are ready to use right out of the box. Cortex’s products fall under this category. Our service catalog is an indispensable tool that brings visibility to your company’s collection of microservices. Among other offerings, It provides information such as the ownership and performance details and metrics of each service, as well as simplifies the processes of incident resolution.

We also have a Scaffolder that lets you set templates for the faster creation of new services. With basic templates at their disposal, developers need only focus on fine-tuning each service and can contribute to the larger project of standardizing services across the project. Service standardization is also made easier with the use of Cortex’s Scorecards. These come in handy for leaders and managers looking to enforce standard best practices across the board and hold developers accountable against them.

Put together, Cortex’s products function as an off-the-shelf developer portal that is tightly integrated with numerous third-party tools, ensuring that your team’s workflows are not disrupted, only managed more effectively.