Using a Developer Portal for API Management
An API catalog is like a super organized library where you can easily find and use different APIs. Private API catalogs include all internal APIs used within an organization. This optimizes API management by identifying redundant code and promoting adherence to organization-wide standards. A private API catalog acts as a centralized repository for all internal APIs, affording comprehensive visibility into an organization’s API landscape.
Private API catalogs yield advantages for both developers and engineering leadership. Developers benefit by avoiding the need to repetitively code common workflows, such as user authentication. Instead, they can leverage APIs developed by other teams for similar purposes. Furthermore, API catalogs provide real-time insights into internal API usage trends, enabling informed decisions regarding resource allocation. Lastly, the centralized nature of API catalogs simplifies the enforcement of an effective API governance strategy across all organizational teams and prevents unnecessary microservices or orphaned APIs.
You can create an API catalog within your internal developer portal, making it part of the overall software catalog in your internal developer portal. Portals contain more than just software catalogs. They provide self-service actions that simplify the process of calling and consuming APIs, eliminate duplicate coding, and provide visibility and context.
You can gain significant value from maintaining an API catalog in an internal developer portal like Port. For more information and a complete demo, watch this webinar.
Using the Internal Developer Portal as an API Catalog
Microservices architectures often have a host of APIs that communicate with each other across a variety of interfaces and methods. By tracking those APIs, you can obtain a high-quality layer of observability and context. For example, tracking API versions, usage and dependencies helps you check that APIs are functioning properly or quickly identify any potential issues.
However, developers might struggle with calling, tracking and deploying APIs. Debugging and troubleshooting require a deep understanding of APIs and the intricacies of the microservices, which not all developers have time to dive into. The same goes for integrating with third-party or new systems, which calls for deep knowledge of each system. There are also security demands, which require collaboration with security teams and comprehending security requirements. And the list goes on.
One of the main advantages of having an API catalog within an internal developer portal is that it can answer these challenges and more by abstracting away complexities and showing developers only the information they need for the API actions they need to take at a given time. This helps streamline and manage the process with efficiency and scale, which reduces cognitive load and frees developers to focus on their core activities, like writing high-performing and scalable code for the APIs.
How to Use API Data in an Internal Developer Portal
An API catalog is a strategic asset that enhances the efficiency, security and scalability of an organization’s API infrastructure. Some practical implementations include:
Troubleshooting and Maintenance
When issues arise, developers can quickly refer to the software catalog to isolate the problem and understand its impact on interconnected systems. For example, by looking at the latest health-check response time or status, you can see whether the API endpoints are degraded, unhealthy or unavailable. Additionally, you can use this information to quickly identify the root cause of the issue and take corrective action.
The software catalog also provides developers with additional context into the APIs provided and consumed by services. This information is valuable as a proactive measure to prevent incidents.
On-Call Response
If a developer needs to tend to an API-related incident, the portal provides guidance in an automated and self-service manner. This streamlined process makes it very easy for the on-call developer to take care of an incident, even if it’s 4 a.m., they just woke up and it’s a mission-critical API.
Onboarding and Training
New team members can use the software catalog as a learning tool to understand the organization’s API infrastructure, speeding up the onboarding process. If a developer needs to add a new feature or develop a new API, they might be wondering whether there is already a similar functionality inside the organization. If so, they can use the endpoint that already exists rather than developing it.
Ongoing Development
An API catalog provides developers with information about existing APIs, preventing them from redeveloping an endpoint that already exists.
Strategic Planning
By building the API catalog inside the portal’s software catalog, decision makers can get a clear overview of the API landscape, which helps with strategic planning and resource allocation.
Demo: Build an API Catalog in Port Using Blueprints
In Port, the software catalog is defined using blueprints.
To build the API catalog, you will define an API Endpoint blueprint. It will contain the data schema for all API endpoint entities you will include in the software catalog. This will aggregate all API endpoints into a single pane of glass, making it easier for developers and stakeholders to immediately visualize the entire API landscape. As a result, they can quickly identify APIs, understand their functions, and monitor their status, performance and health.
Define a blueprint that includes:
- HTTP method
- Endpoint health-check status
- Latest health-check response time
- Example responses
- Example requests, which make it easier to onboard this service and endpoint and understand how to use this API
Now, connect the API endpoint blueprint to additional Port blueprints by using relations. In this case, you’re connecting to Running Service, Environment and Service blueprints.
These connections make it possible to leverage the additional context that the developer portal provides. Developers will be able to ask (and answer) questions such as which service does this API endpoint belong to, or what is the response time of the API running in production in the U.S. region.
API Software Catalog in Action
Now that you’ve built the API catalog using blueprints, see what it looks like. To add the APIs to the catalog for the first time, scan your API specification file, such as Swagger, OpenAPI, AsyncAPI or Protobuf.
The API endpoint section in the software catalog displays every endpoint in the organization, with information such as when it was last updated, its HTTP method, health status, the latest health-check response time and which service provides the endpoint. This page allows you to track how the APIs are performing.
The endpoints in the image below, both in test and production, are healthy, and the response time is low and acceptable.
By looking at a Running Service, you can see the endpoints it is exposing. You can use this, for example, to see the difference between different deployed versions (which can be helpful with feature flags), comparing testing to production or understanding if there is a certain performance degradation in newer versions or between regions.
API Management, Simplified
An internal developer portal is a great solution for managing API complexities in a microservices architecture. It serves as a strategic asset, significantly improving the efficiency, security and scalability of your organization’s API infrastructure. By providing a centralized, user-friendly and self-service interface, the portal simplifies API processes like troubleshooting, maintenance, onboarding and strategic planning.
The API catalog in Port’s internal developer portal offers comprehensive and real-time insights into the health and performance of APIs. Developers benefit from reduced cognitive load and automated workflows, allowing them to focus on core development tasks and innovate without having to spend time figuring out the intricacies of API management.
