How to Integrate Your API Management or Developer Portal with Solace

Here at Solace we see increasing interest in unified API management, i.e. giving developers self-service access to all types of APIs – REST APIs and event APIs – in one place. That interest was behind a partnership with Gravitee that we announced recently, which provides an out-of-the-box solution based on PubSub+ Platform and Gravitee’s API Federation.

We know many of our customers have and use other API management and developer portals, and if you’re in that boat you might think you need to wait for us to announce a joint solution with your API management solution or developer portal of choice—what if I told you that you can build your own integration with publicly-available APIs?

Once we found out apigeeX’s Dev Portal now supports AsyncAPI, we realized it would make a good example for demonstrating how such a custom integration works.

Benefits of Integrating your API Management with our Event Portal

Let’s first look at what a custom integration between Google’s ApigeeX and PubSub+ Event Portal makes possible in terms of developer experience and back-office API Management?

Developer Experience

First and foremost, the goal is to make event APIs – documented using the AsyncAPI specification – available to developers so they can discover, learn about, and get access to events.

You can watch the video below or expand any of the sections to scroll through screenshots of the developer experience.

Discover Async APIs in the Dev Portal

Figure 1: AsyncAPIs are presented in the apigee Dev Portal alongside REST and other APIs

Figure 2: A developer can explore the documentation of the event API in the familiar AsyncAPI format

Developer’s Application Access to Event API Products

Figure 3: To gain access the developer heads to “apps” menu. Here’s an example of an app registered by a developer. It has access to the API Product associated with the “Shipment Tracker API”

Figure 4: The developer can retrieve the app’s OAuth secrets required to obtain an API token

Connect and Receive Events

Now it’s time to connect to the event API. Armed with information from the documentation (server endpoint, event protocol, channels they can subscribe to) and the application secrets, it’s easy to connect.

They head over to their trusted postman which can issue REST calls and connect to MQTT.

Figure 5: First the developer uses the app’s secrets to obtain an API token (JWT)

Figure 6: Then they set up a MQTT connection in postman – presenting the JWT for authorization. Once they have added subscriptions to channels (topics) events start to flow in.

Managing Event APIs and API Products

What happened in the background for the event API to be discoverable and accessible in the dev portal?

1. Event API Products were defined in PubSub+ Event Portal
2. Corresponding API Products were created in apigeeX

I’ll explain the details of the automated integration later; for now, let’s focus on the event and API teams’ back-office tasks.

You can watch the video below or expand any of the sections to scroll through screenshots

Event API Products were defined in PubSub+ Event Portal

Figure 7 The Event Governance Team created an Event API Product with various Plans (service level agreements) and associated it with an event broker and the event API (Shipment Tracker API in our example). They then made this event API product publicly available.

Corresponding API Products were created in apigeeX

Figure 8: The integration replicated the Event API Product to apigeeX creating API Products. These are the products visible to the developer in the Dev Portal.

Figure 9: The integration adds information about the source Event API Product so it can trace back to the source.

How does it work?

In this section we will peel back the layers and describe how the integration works.

Components and High-Level Interactions

Let’s look at all the components involved:

• ApigeeX Dev Portal: the developer portal that developers interact with to find APIs and register their apps
• Application: the application that the developer creates. We simulated this app with postman in the sections above.
• PubSub+ Event Broker: the event broker where the event API is accessible. As it acts similarly to an API Gateway, we could also call it an “Event Gateway”.
• Google apigeeX API Gateway: the API gateway hosting all the required API Proxies for the integration (more on these later)
• PubSub+ Event Portal: the event governance platform that lets you manage events, event APIs, and event API products.
• apigeeX Platform: the API management back office

As you can see the interactions flow through the apigeeX gateway as we chose to implement the integration completely in apigeeX:

• The integration provides a REST API for discovery of event API products and to subsequently import these to the developer portal and apigeeX platform. This includes uploading AsyncAPIs to the developer portal as well as creating apigeeX API Products that represent event API products
• Developer portal requests to the core apigeeX platform are proxied via the gateway – this allows us to hook our integration into requests such as adding an API Product to an app or deletion of apps. This allows us to create and manage app registrations and access requests in Solace’s event portal – which are required for the configuration of runtime access on the “event gateway”.

APIs and API Proxies of the Integration

The integration consists of three API proxies that are deployed to the apigeeX gateway:

• Platform API Proxy: intercepts communications with the apigeeX Dev Portal.
• Event Portal Integration API: provides management and integration endpoints for Solace Event Portal’s API management resources.
• OAuth API: issues JWT tokens for authentication and authorization to apigeeX hosted REST APIs and Solace Event Brokers.

Platform API Proxy

The Platform API Proxy intercepts all API calls from the Dev Portal to the apigeeX platform. This provides a hook to propagate relevant user activities to Solace Event Portal. For example, when an application is created in the Dev Portal it is added as an application registration to Event Portal provided the targeted apigeeX platform API created the app successfully.

Event Portal Integration API

Integrates with Event Portal via its API management resources. It exposes configuration endpoints to set up credentials and API tokens required to connect to Solace’s REST APIs and to the apigeeX Dev Portal.

It also provides management endpoints to discover available event API products in Event Portal and how these can be imported as a set of API Products into apigeeX. As apigeeX does not have an explicit concept of a plan, event API products with multiple plans are unrolled into multiple apigeeX API products – one for each plan.

Finally, it exposes integration endpoints that are invoked whenever a relevant API activity in the “Platform API Proxy” occurs that need propagation into the event portal.

OAuth API

OAuth endpoints to obtain and verify a JWT for API access to apigeeX Gateway API Proxies and Solace Event Brokers.

It also includes endpoints to set up keys and other resources required to issue JWTs.

Solace Platform APIs

The key enabler for this integration is the Solace Platform APIs for API Management. It provides a simplified interface to Event Portal that is aligned with the model of API management Platforms. See the Getting Started Guide for a good first overview of the API.

Particularly important is the section on Event Portal Prerequisites that documents what  you need to do in Event Portal to be able to share Event API Products through these APIs.

Want to try it out?

Follow the steps in our  Codelab that guides you how to set up  and configure ApigeeX and Solace Event Portal, and deploy an integration template that we have made available on Github.

Conclusion

I hope I’ve helped you understand how event APIs can be brought into the world of traditional API management by leveraging our publicly available APIs and ApigeeX’s support for AsyncAPI. Whether you’re enhancing an existing portal or experimenting with a proof of concept, this approach provides a practical blueprint for bridging the event and REST API worlds.