Developers need all the information they can get on APIs to get them to work in alignment with their vision. There is no dearth of knowledge in the software development industry today, but only when that knowledge is documented well is it of use to others. In the context of APIs, developer portals offer an effective way to document and communicate relevant information.
In this article, we answer the following questions about developer API portals:
- What is a developer API portal?
- What is the difference between external and internal developer API portals?
- Why should you build them?
- How can you effectively build and manage API portals?
What is a developer API portal?
A developer API portal is a centralized virtual hub that contains the documentation for your software’s APIs. With proper information at their disposal, the users of the portal can learn how to use the APIs and request access if they need to do so. Companies can benefit greatly from these portals as they allow developers to learn everything they need to know and maximize the potential of the APIs. Another way to look at it is that these portals provide support to engineers trying to work with APIs that are new to them.
Depending on the purpose and target audience, developer API portals are of two types: they can be external or internal-facing. Both are tasked with providing knowledge and support to developers, so they are not particularly different in that sense. Although developer portals are more focused on internal use cases today, there is a whole class of developer API portals that are more targeted towards API consumption by developers outside of the company. Let us further examine each type of developer API portal.
External-facing developer API portals
The external-facing developer portals are usually primarily concerned with API documentation for developers outside of the company. The focus lies on helping these developers understand how the API works and how they can use it. They can look up details such as status codes, response types, and SDKs.
Additionally, companies use these portals to authorize access to the APIs, as well as facilitate interaction between external developers and the team.
An external-facing API portal is usually posted to the software’s website. While there are dedicated tools for API documentation, you can also choose to manually set it up yourself.
Why should companies develop external-facing API portals?
There are multiple advantages to setting up an API portal for external developers to benefit from. Some of these include:
- Increased outreach and engagement: An API portal for external developers is essentially a way to make your software more accessible to those with more technical know-how. For companies, APIs act as deeper links to the outside world. The portal is an opportunity for teams to convince others to adopt their APIs. The developer community can play with the API and figure out new ways to integrate or use it. API adoption by external developers can do wonders for the company, as it opens up new avenues, including opportunities for monetization and to extend their reach deeper into the community.
- Valuable insights: A microservices architecture is difficult to maintain. While the developer API portal makes the API more accessible to other developers, it also gives the company a few insights of its own. They can monitor API usage and adoption via alerts. For example, if the APIs are not witnessing widespread adoption, the company can understand why that is the case, which subsequently informs a strategy for improving the API and the software. In this sense, it also works as a feedback portal for the team that built the APIs.
- The impetus for innovation: By sharing information about the APIs, companies are already encouraging external developers to innovate. However, developer API portals also facilitate interaction between the team and the users of the portal via channels such as community forums. This can lead to collaborations between them or increased innovation within the team itself.
- Ease of registration: API portals also handle registrations. They centralize the authorization process, which makes it much easier for the team to onboard new users of the APIs and keep track of their usage.
What are some best practices around external developer API portal development?
There are many tools to choose from to help you set up an external API portal. However, tools are ultimately limited to following the instructions you give them. Here are a few things to keep in mind while designing and developing your portal:
Center clear communication
One of the main objectives of an external-facing portal is to inform other developers about your API and how it works. You will see little developer engagement with the portal if the documentation in your portal is highly vague or dense. Clarity is also of the essence when attempting to onboard new users. The point is to support and guide them, not to add to their confusion. You can, for instance, make use of diagrams or showcase sample workflows for better comprehensibility. Prioritize communicating clearly and effectively with your audience so that they can take advantage of the portal and use the API as they see fit.
Publish an API catalog
If you have multiple APIs, organizing them in a catalog will make it easier for developers to find what they need. Ease of navigation also contributes to how likely it is for the developers to re-use the API.
Providing a one-line description of how each API can be useful to developers is also beneficial. This is especially important when you have multiple APIs on display since it ensures that developers are guided to the right API.
Explain in simple terms
Following the previous guideline is the idea that the simplification of ideas and processes contributes to clarity. Developers with varying levels of experience will approach the portal with questions about your software. Although it is impossible to preemptively answer every potential question, it is good practice to provide robust instructions for getting started. A “Getting Started” guide with step-by-step instructions or a flowchart is a step in this direction. In your documentation, you can also insert chunks of code in popular programming languages to give developers an extra push.
Provide a space for interaction
The users of your developer API portal should be able to interact with each other and with the team. This can be achieved via Slack or Discord channels or through forums. Doing so allows them to communicate feedback and also fosters collaboration and innovation, which is a great sign for your team.
Another form of interaction can be made possible through interactive tutorials. Invite the users to try out the API by creating requests within the documentation itself. You can include responses in it so that the developers can see how the scenario plays out.
Keep users in the loop
This goes without saying, but your developer API portals must be up-to-date at all times. Make sure that any changes you push to the API are reflected and announced in the portal so that the external developers are not left in the dark.
Internal-facing developer API portals
Maintaining an external-facing developer API portal can boost your APIs’ visibility and usability. At the same time, there is a need for a similar API portal for internal use. Let’s say your team has a hundred different microservices and is trying to consume other APIs. How do you know what APIs are out there, how to consume them, what their shapes are, and ways to stay up-to-date with them? An internal-facing API portal is an important part of a developer’s ecosystem, as it acts as a hub with information about all the APIs built and used by the team.
What are the benefits of having an internal developer API portal?
The power of an internal-facing API portal must not be underestimated. Here are a few reasons we recommend investing some time and effort into setting one up:
- Managing your APIs in one place: Thanks to the complexity of a microservices architecture, it’s easy for developers to lose track of the APIs they are using. Sometimes, they may end up developing the same functionality without realizing an API already exists. An internal-facing API portal comes to the rescue by acting as a one-stop solution for all of their API-related needs. There is no longer any need to waste time looking for the documentation. Instead, they can quickly find the APIs they need and use that time to continue to innovate and improve the application. API reuse goes a long way in speeding up the development process and enhancing the developer experience.
- Easier onboarding: Onboarding new engineers and getting them up to speed also becomes easier as a result of having your API documentation organized and placed in one central portal. Recruits need no longer worry about bothering senior engineers when they cannot locate an API. The developer portal contributes to a smoother onboarding experience, in addition to making them feel more self-sufficient and boosting their confidence.
- Increased productivity: The impact of having easy access to APIs must not be underestimated. Because of it, not only do developers have more time and energy to give to other tasks, but they are also more comfortable with the resources. Increased proximity to these resources enables developers to use them with greater ease. They can learn how to use the APIs and test them in their projects. With clear documentation assembled in a single place, it is more likely that the team understands the APIs better and can put them to use according to their objectives.
- Encouraging innovation: APIs open up new channels for communication as well as ways to solve challenges by allowing developers to use each others’ work. A developer API portal further facilitates this process by making it easier to access these APIs.
- Enforcing documentation standards: With the entirety of your API documentation in one place, you can enforce standards and best practices for documentation with lesser resistance. Being able to look at each API lets you identify any inconsistencies in their documentation more easily, and hold the developers accountable.
- Powerful monitoring: A developer API portal can host all your APIs, as well as monitor them so that you have updated information at all times. Most portals can monitor the number of requests per API, but some also allow users to examine individual requests. API health must not be neglected and a portal with monitoring capabilities makes it possible for developers to keep track and fix any issues they notice.
- Easier transition to an external portal: If the API is consistently delivering value to your team, you may consider sharing it with partners or opening it up to the public in the future. An internal API portal makes it easier to identify such APIs and polish their documentation for external use.
How should you set up an internal-facing API portal?
The initial set-up for an internal-facing developer API portal requires some effort, but it is sure to pay off in the long run. We have listed a few ideas to keep in mind as you get started:
Pick a location for the portal
There exist various tools to support your API portal development. You can choose to keep your API documentation separate from the rest of your architecture. This would mean using a tool like SwaggerHub to design and develop APIs in a dedicated portal that only does API documentation.
On the other hand, you can also integrate your API portal with your larger developer portal. One of the many features of a internal developer portal is also the management and documentation of APIs. If you are adopting a developer portal, then this is the route that you should be going, as it is unlikely that you need a dedicated API portal in your organization. Ideally, you want to integrate it with the rest of your assets, if you are already documenting things like on-call rotations, runbooks, and dependencies. Putting the APIs in the same place makes them more discoverable and easier to access. The tools you use to build your developer portal will help you ensure that assets do not get mixed up or confusing to navigate through.
Choose a layout that allows easy access
You can have each microservice expose its own API documentation using plugins. Spring Boot, for example, is a plugin that gives the microservice a URL that you can navigate, to access its API documentation. This approach is less recommended because all the APIs need to be in a single place. This is because you are building a developer API portal, which is a central hub where you can go to find anything you need.
Build a solid internal search system so that developers can easily access the APIs they need. You can choose to make the process simpler by adding the option to filter the searches. The objective is to make developers' lives easier, as opposed to needing to know where to find the documentation for each API, which defeats the purpose of the portal.
Make sure developers have everything they need
An incomplete portal is a magnet for confusion, and it can slow down or even block the developers’ workflows. The documentation for each API should be comprehensive. This includes a clear description of the API, information about the endpoint, and a sample response. This means that the portal should have the functionality to let developers write detailed documentation and add anything they deem relevant to it.
To make it more accessible, you can also consider including code snippets. Code snippets (static or interactive ones) allow the developer to familiarize themselves with the functioning of the API quickly so that they can go ahead and use it almost immediately.
Graphs are another great way to visualize complex data and highlight important information that will otherwise take developers some time to sift through. They are particularly useful for monitoring purposes.
Finally, ensure that your alerting system has been established properly, such that developers do not receive unnecessary notifications but can trust the portal to relay any critical information on time.
Govern resource access
Although universal access to all APIs sounds ideal for the team, there are times when developers accidentally modify or damage resources. You can decide to restrict access to certain APIs, as well as monitor API activity to ensure no damage is done. For example, you can allow certain developers to only access the APIs that fall under the project they are working on. Be sure to assess your team’s needs before making any governance and access-related decisions.
API governance also includes the ability to control the publishing and versioning of the APIs. The portal should let developers access the version of the API they request.
There is an added benefit of ensuring that registration and API access are carried out securely. The portal can push the team to enforce certain rules surrounding access and sharing that ensure the security of the internal APIs.
Automate where possible
Setting up and maintaining an internal API portal is a lot of work, so use automation wherever you can. Instead of having the team manually define their API documentation, a lot of web frameworks automatically generate it. The bottom line is that your APIs must be documented in a single place and you can use automation to generate that and upload it to wherever your central hub is.
Once that is done, ensure that every single microservice is exposing its API documentation somewhere. So you want to use automation, either as part of continuous integration or as part of your developer portals’ tooling to enforce the requirement that everyone is exposing developer documentation.
Build your developer portals with the right tools
There is no shortage of tools to help you build your own developer API portal, whether external or internal. There is a solution for every kind of team, from those building cloud-native applications to those with a predominantly self-development approach. Most importantly, remember your needs, purpose, and target audience when you choose your tools.
Backstage, for example, is a handy tool from Spotify that lets you set up and customize a developer portal. It includes a service catalog, documentation functionality, and software templates, which you can combine to develop an API portal. Because it is open-source, you can choose to modify the platform in a way that serves your developers’ needs. However, Backstage demands a significant amount of effort from your team in terms of setup and management of the developer portal.
At Cortex, we offer a bundle of services that can come together to form a robust developer portal that can, amongst other assets, house the data on all of your APIs. These are easier to use in comparison to Backstage’s offerings. The service catalog is the central hub that puts all your microservices and any related assets on display. Your APIs can be documented here too so that your developers can easily access them. You can complement this with scorecards, to enforce best practices surrounding API development and documentation in your company.
A developer API portal needs to respond to your developers’ technical as well as the company’s business needs. Consult the best practices in this article if you feel stuck at any point. However, remember the main idea, which is not to have the information and data scattered across many different locations but to instead pull it into a single place. Having clarity on this will help you make good use of the tools, which can make your developer API portal easy to manage, navigate, and access.
