It is no secret that microservices architectures lend themselves to complexity. This can be a small price to pay when your workflows and processes are organized to ensure that everyone on the team is informed, accountable, and content. Setting up an internal developer portal is one of the best things you can do for the team, as it is an easy, surefire way to get your services, resources, and processes in order.
The magic of the internal developer portal lies in its ability to assemble all the parts of the development life cycle. This includes APIs, which can often be difficult to manage and maintain internally. Your internal developer portal should also be your internal API portal in some sense.
In this article, we discuss how teams can stay on top of their API documentation with the help of their internal developer portals with Cortex.
Why should your API documentation be in your internal developer portal?
The internal developer portal pulls together the various parts of your software architecture into one central place. The guaranteed visibility reduces confusion, making teams more productive and efficient. When your entire architecture, including the microservices, dependencies, resources, and ownership details, is in this portal, it makes little sense to keep your API documentation or API portal separate. Instead, they should be a part of your standard internal developer portal so that developers can access any asset they need with little difficulty, including the APIs.
Keep in mind that an internal API portal is different from a public-facing one. While the latter is geared towards an external audience and primarily concerned with helping external developers access and use certain data, the former is more service-oriented and meets more context-heavy demands of the team. It aggregates the internal APIs that are connected to your microservices and not exposed publicly. An internal developer portal that houses your APIs can help developers answer questions about any API, such as:
How reliable and stable is this particular API?
Who is this API being used by?
Is this an AsyncAPI or is it an OpenAPI? Is it an HTTP API, or is it gRPC?
How do I use it? Is it even available for consumption internally?
These are all different questions around the parts of the development workflow that have to do with using an API, which is what ultimately matters internally. An external API portal, on the other hand, is limited to making certain APIs available to others. So when you are thinking about APIs from an internal standpoint, you are generally thinking about factors such as the services you are using or details of service ownership across teams.
Integrating your APIs into your internal developer portal is crucial to improving the developer experience as the visibility allows teams to easily access the APIs they need to build the software. They need not waste energy rewriting the code from scratch and reinventing the wheel. Developers also tend to spend great amounts of effort and time looking for APIs or pursuing related inquiries.
Visibility is essential not only for API discovery and access but also to test the APIs for the specific use cases of the team, as well as to monitor any issues with performance. An internal developer portal then contributes to streamlining the process of discovering, testing, monitoring, and reusing APIs, making the team’s software development workflows more efficient.
The role of the service catalog
Since the internal approach to APIs is so service-oriented, it follows that your API documentation and portal be closely tied to the service catalog feature of your internal developer portal. The service catalog is an archive of all the microservices that comprise your software architecture. When you look up some information about a service in the catalog, you are made aware of the entire context of that service. This means that the catalog will list everything you need to know, from what the service does, where it is deployed, and who owns it, to how reliable it is.
When working with a particular microservice, you may be interested in knowing which specific APIs the service exposes. To use and make sense of an API, it is essential to understand and work in the context it is situated in. Storing your API information in an API portal allows you to make connections with the relevant services that live in the service catalog of your developer portal. Accessing them from elsewhere makes it difficult and time-consuming to establish those links.
For teams using a microservices architecture, it is impossible to run your development processes efficiently without the help of a services catalog. The sheer complexity of the architecture is reason enough to invest in one. The same goes for the number of APIs teams have to regularly manage and use. In that context, ensuring that they are easily discoverable and can be linked to the appropriate microservices is no longer nice-to-have, but becomes the bare minimum for effective API management internally.
How does Cortex help integrate your APIs into your internal developer portal?
Cortex supports various specifications, including both the OpenAPI and AsyncAPI specifications. Because every organization is likely to use its API documentation in slightly different ways, Cortex remains agnostic to the source of your APIs. Some teams might automatically generate their API documentation. For example, users of Spring Boot as their web framework can employ plugins that auto-generate the specs. Other teams might prefer sticking to manual definitions with a YAML or JSON file. The diversity in spec generation across organizations and teams is not a barrier to using Cortex to manage your API documentation. In this section, we take a look at the service catalog’s API Explorer to see how it can support your team’s API management practices.
Getting started with the API Explorer
To find the API documentation for a particular service, open the service catalog. In the image below, the sidebar displays a dedicated section for the API Explorer for a service called credits-infra. This tool can have multiple API specs associated with it. So if you have different versions, types, or environments for the API that the team will need to use, you can define them all in this section.
Defining API documentation
There are a few different ways you can define API documentation in Cortex’s service catalog depending on how your APIs are stored at present.
Because OpenAPI has support for extensions, the Cortex service descriptor file is a fully compliant OpenAPI spec. So you can choose to add and implement your API documentation in the service descriptor itself. That way, everything lives in a single place and can be accessed easily.
Alternatively, if you already have API documentation stored someplace and you only want Cortex to point to it, you can do so in the following ways:
For existing specs, you can add a link of type openapi by feeding the URL to the YAML or JSON spec file. It could look like: myinternalmicroservice.cortex.io/openAPI.JSON. Cortex will load it dynamically and show it to you in the UI. This is useful if you are automatically generating your OpenAPI spec and is available as part of the microservice.
If you are generating or manually creating the OpenAPI specs and have checked into your Git repository, you can also create a link of type openapi and use what we call a relative link to add the spec. A relative link is simply a URL that refers to a file in your Git repository. Once added, Cortex will load the file automatically and display it in the API Explorer.
Finally, you can also upload the spec via API. If you are generating or merging specs with your own custom tooling, you can add the specs using your Entity Tag. This allows you to directly send a JSON or YAML file to Cortex’s public endpoint. You can upload one API doc per entity, which will then be displayed in the API Explorer.
AsyncAPI specification users can follow the same instructions (with links of type async_api instead of type openapi) to add their specs to the service catalog.
The bottom line is that no matter where the API documentation lives, you can access it in your internal developer portal. Instead of distributing the information across an API portal, an AsyncAPI portal, and a URL for the microservice, for instance, you can pull it all into a single place.
Enforcing API-first development practices with Scorecards
Another benefit of integrating your API documentation with the internal developer portal is that you can then enforce this practice with a Cortex Scorecard. If you decide to use a separate API portal internally, it is difficult to confirm that a service has the documentation at all. Instead, with Cortex’s service catalog, you can define a scorecard and lay down the expectation that all the internal microservices have an API spec defined somewhere. Although building an API contract requires careful planning and collaboration, it is ultimately more beneficial to design reliable APIs before writing code. Using scorecards will enable you to promote an API-first development culture in your team earlier in the development process.
Although encouraging teams to make changes in how they work can be difficult, the scorecards are customizable and automate the process to give leaders a hassle-free experience in that regard. They can enforce the idea that every microservice must be accompanied by its API documentation and encourage the adoption of API-first development across the board.
More generally, Scorecards can help set API usage and development-related best practices and standards. This is important to maintain standards of developer productivity as well as product performance and quality.
Notifying users about breaking changes
Often when you are using API-first development, you want to make sure that you are conforming to that contract. So after exposing and documenting an API with its shape and endpoints, you might decide to make a change to it. If you make a change that is backward incompatible, how do you know whom to inform? You need to identify the users of that API and let them know that you are making a breaking change so that they can update their service to account for that.
Cortex does this automatically, with the help of its integrations with many of the tools that are likely to already be part of your workflow. If you have API documentation linked to Cortex, we can send notifications to the service owners of affected services. It will detect the change when you are making it based on the dependency graph and notify those who depend on the service. For a microservice called credits-infra, for example, the system will send a notification that looks something like this: “Service credits-infra is making a backward incompatible change with the specification, here is a change.” Once they are aware, users can account for the changes before they go into production and are forced to deal with the resulting issues.
With access to information about dependencies and ownership, you can start building automation around sending notifications when changes are made to the specs. This is a more effective alternative to sending off a Slack message to everybody to ask who is being affected by the change. This is another reason we recommend having your API documentation live in your internal developer portal instead of storing it in a separate third-party space.
Add your APIs to your internal developer portal today
When your team uses hundreds and thousands of APIs, finding the right one is not always easy. An internal developer portal with a service catalog can save your developers the energy they would otherwise spend playing a game of hide-and-seek that is fun for no one. An internal developer portal increases the proximity of your APIs to your microservices, making the process of locating them hassle-free.
Cortex offers the complete package for integrating your APIs in your service catalog. In addition to the wealth of information the catalog stores about each of your microservices, it comes with a handy API Explorer. This tool helps you add your existing API specs to the relevant service in no time, no matter where they are stored. You can also set it up to notify API users when a breaking change is being made to the API to avoid unwanted consequences in the system. Thanks to our rich Scorecards feature, you can also enforce API documentation best practices across the team and enforce a culture of API-first development.
Try it out today by booking a demo with us!
