Unlocking the Power – The Importance of API Registration
David Manolitsas is a software developer at Marlo. In this article, he discusses the importance of API Registration. Marlo specializes in the delivery and support of APIs and microservice architecture. They also provide DevOps Services and digital enablement solutions.
Consider the following. Our API gateway is implemented; our scaling lifecycle management is being completed. We have this powerful tool at our disposal. But how do we utilize all the capabilities a new API gateway provides? Often, we see it with our clients; this sort of conflict or tug of war between development teams looking to improve their delivery cycles and publish their APIs to their Gateway. Platform management teams managing the Gateway, look to apply API governance, and it’s a sort of conflict that sparked this interest and the topic of API registration.
In today’s interconnected digital landscape API, gateways are essential for secure and scalable data exchange. API registration is the process of making an API available through an API gateway. API registration is about empowering developers to improve the experience of building their APIs and speeding up development times to allow developers to utilize their Gateway’s capabilities. API registration also serves as a building block for API governance and provides organizations with the tools to govern their APIs. API registration also promotes API discoverability by emphasizing the importance of API design and documentation. These are the core pillars that make up the API registration process.
Typically, after implementing a gateway, we see our clients focus on infrastructure and operational teams to support the API gateway’s new capabilities. This can often feel like one step forward and two steps back. As new problems arise, such as existing API teams need to migrate their APIs to the new Gateway. New API teams that are formed require a lot of training and documentation, updating standards and workflows to understand the new Gateway’s capabilities. API registration aims to create a transition solution to manage the onboarding of an API while providing additional benefits across the business. This includes an automated API onboarding experience, applying and verifying API Standards, ensuring that deployments are consistent and repeatable, and allowing developers to manage their environment workflows.
API registration starts with an open API specification. Typically, when a new Gateway is implemented, it involves training development teams to understand gateway-specific languages or configurations. API registration aims to address these issues by removing a lot of that overhead. We achieve this by utilizing the Open API specification. We can learn all the information we need about an API from its specs, such as server URL, path, request-type responses, etc. We can then take this information and generate a Gateway-specific configuration that we can use to onboard an API to its target Gateway. We then provide the ability for developers to enhance their API by providing a small uplift to the API spec in the form of Open API extensions. These provide developers with the ability to enable specific gateway features. This allows developers to be flexible in terms of how they want to customize and build their applications before publishing them to that Gateway. Developers can use extensions by using gateway agnostic configuration because the API registration project has no preference as to which Gateway it’s targeting. We achieve this by mapping generic configuration to Gateway specific values, which will then be used to create our gateway configuration files and then deploy to our target gateway.
As part of the API registration project, you can go a little bit deeper into some of the API project’s capabilities. API registration runs as a pipeline added to an existing API development workflow. This is made up of various modules with distinct roles and responsibilities.
Lint module – A lint module is responsible for linting the API spec, ensuring it’s correctly formatted and that the provided data is correct. It uses a fully configurable schema, which can be customized depending on different use cases and business requirements. Another thing to note about the lint module is that it can be run in parallel with other pre-existing linting tools used worldwide.
Validate module – The validate module is responsible for doing another validation over the API spec. But what differentiates it from the lint module is that it focuses on the gateway agnostic configurations developers provide. We use validation rules to ensure that the values provided adhere to the API development standards set in place by an organization. This module is responsible for validating the configuration defined by developers as part of the Open API extensions. We achieve this by using validation rules we call Guardrails. The guardrails define the boundaries for how a developer can implement the specific gateway features within the API spec. The guardrails to find clear standards for API development exist in a centralized repository for API standards policies. They define clear API Standards that a developer can use as part of the API spec. Guardrails exist in a centralized repository for API Standards. We have a hierarchy structure where we can have lower precedence layers overridden by higher precedence layers. This is to cater to the different layers of governing that may be required for various use cases. For example, different environments or teams may need varying levels of API governing.
Process module – This is responsible for mapping our generic configuration to our gateway-specific values. In the process module, we also introduce the concept we call defaults. The defaults are a set of Open API extensions injected into the API spec before the processing begins. This allows organizations to apply gateway features to these services automatically. Similarly to the guardrails, they exist in a centralized repository for API Standards and promote API standards policies. They define and apply specific gateway features automatically to a developer’s API. Another capability that the defaults provide is that of API authentication and API security. API registration allows organizations to apply API authentication across their entire API portfolio automatically. This is achieved by extending the default configuration. This removes much of the developer overhead for implementing API authentication security on their services and helps streamline the developer experience of building their APIs.
Apply module – The Apply module is responsible for generating our gateway configuration files, which will be our final deployable artifacts, which will then be used to deploy to our target gateway. It takes the configuration from the Apply module and applies it to a template file, generating our final deployable artifacts, which we can then use to publish our API to its target gateway.
We can run these modules in various configurations to suit different use cases. For example, we may only want to run the lint validate module on developers’ feature branches or some combination of these modules. The API registration pipeline gets added to an existing workflow.
This is an overview of the API registration project. As a quick recap, the Open API spec is taken as input. It’s then validated to ensure that it’s correctly formatted and that any Open API extensions provided by developers are not breaking any of the guardrails set in place by their organization. The process module will then apply any default set by the organization to a template file and publish it to a target gateway. Since we have the Open API spec available, we can take that API spec as part of the publishing stage and deploy it to an API developer portal, whether an internal or external facing developer portal. This helps to drive home the idea of promoting API discoverability and API documentation.
An API-first approach involves developing APIs that are consistent and reusable. API registration places importance on establishing a contract early in the development lifecycle for how an API should behave and emphasizes the value of API design documentation using an API description language, such as Open API. This approach establishes a contract between services early in the development lifecycle. This allows API development teams to work in parallel and build their applications in parallel because it’s been established early on about how an API will behave.
An API registration enables an organization to build an API portfolio with an API-first approach. API registration establishes consistent API development standards, reduces friction within development teams, and helps accelerate delivery cycles. Today, more teams are designing and building applications as a collection of internal and external services. The process of applying and establishing API governance can often be met with uncertainty and doubt. An API registration aims to address these issues through the use of guardrails and defaults. It allows organizations to easily govern their APIs, apply API governance, and define how they want to govern their APIs for their specific needs.
