Are you wondering how and where to integrate your developer portal with your API gateway? Are you unsure where to begin?
Developer portals and API gateways integrate in several different ways. Here we present some key areas to consider, and then we will highlight how at Pronovix, we can manage the different API gateway integrations.
Synchronized Documentation
The developer portal needs to provide accurate and up-to-date documentation for the APIs exposed by the gateway. This includes details on the API endpoints, request/response formats, error codes, and usage examples. Ideally, when an API on the gateway is deployed or updated, the change should be immediately reflected in the developer portal. Taking a step back to the API design, we can state that when an API specification reaches a certain level of readiness, for example, when an updated API specification is approved and merged into its main Git branch (or whatever else happens to be your particular trigger action), then it gets deployed to the API management platform and also to the developer portal simultaneously. Thus, through a shared workflow, there is an implicit integration between API gateway and developer portal that keeps everything synchronized.
Try Out Feature
Developers like to be able to try out an API to test and experience how the API works in practice. Many API renderers, including SwaggerUI, have a ‘Try Now’ button that enables them to connect to a sandbox or mock API service for this purpose. The choice of whether to offer a mock service, sandbox API gateway connection or production API access depends on a company’s business model. Either way, the integration is technically identical and relatively straightforward.
For its ‘Try Out’ functionality SwaggerUI offers an Authorize window supporting any security schemes that the OpenAPI specification affords. In some cases it is possible to provide hard-coded API keys, or ones provisioned by the Gateway. This can be a global or a user-specific try-out key for a non-production environment, and it can be stored and managed in the developer portal.
Access Key Provisioning and Approval Workflow
In order to be able to try out an API from the portal or from another tool, a developer needs an access key or a similar form of access authorization. This could be an OAuth2 client ID and client secret, an API key, a JWT bearer token, or basic HTTP authentication. Access keys can be provisioned automatically or via an approval workflow.
In practice, we see many variations of these key provisioning and approval flows with various degrees of complexity. Access key provisioning to sandbox API gateways is often fully automated via bidirectional integration with the sandbox API gateway, as this is a low-risk environment. Conversely, access key provisioning to production environments is often a partially manual process and governed by compliance regulations: the workflow is typically initiated on the developer portal via a request form, then passed to a ticketing system or similar, where the human approval process happens in some form, and eventually access keys are passed to the developer in a secure fashion outside of the developer portal. Some companies use their identity provider (IDP) or customer relationship management (CRM) system as their source of truth, from where access keys flow to the API gateway and to the developer. Other companies use the API management system (aka API gateway) as the source of truth. For a better developer experience, many companies let the developer view and sometimes even manage access keys on the developer portal.
Integrations between the developer portal and API gateway can therefore take several forms, all of which could live side-by-side in a truly full-featured implementation:
- Bidirectional integration to request and receive (sandbox) access keys.
- Bidirectional integration to manage (e.g. change, delete, renew) access keys.
- Integration with a ticketing system to pass an access request to.
- Integration with an identity provider or API gateway to receive and display (production) access keys. This is quite rare.
One Solution for Different API Gateway Integrations: Zero Gravity
As is obvious, not all three integration areas are equally simple and straightforward. Also, depending on the API gateway, there might be other capabilities you would want to integrate with. Still, you can start with one or two feasible integrations and work your way up as your API program matures. Thinking in terms of separate integrations and splitting these up helps you take smaller steps and succeed quicker.
At Pronovix we can help you with your integration in a fast and effective way through our Zero Gravity Developer Portal solution.
Automated documentation flow into the developer portal is straightforward in Zero Gravity. A comprehensive set of APIs allow to programmatically create and update documentation. These CI/CD APIs cover all documentation contained in the developer portal, not only OpenAPI specifications. This implicit integration is therefore completely gateway agnostic.
Try Out is natively offered in Swagger UI for REST APIs, provided a backend is configured that answers to API requests. At its core, ‘Try Out‘ functionality is driven by the content of the OpenAPI specification file, in particular the server and authentication blocks. This integration is also gateway agnostic.
Key provisioning can be fully automated if an Apigee API gateway is connected to the developer portal. A developer can view their app keys in the portal at any time. Since approval workflows can vary wildly, implementation of the necessary request forms and API calls is a custom feature.
All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.
