You can use API Management (APIM) to manage Event API products created in Event Portal. To get started, review this page to familiarize yourself with the concepts and requirements to use the APIM/DevPortal.
API Concepts
The API has two core concepts:
- Event API Products package one or more event APIs and associate them with endpoints (gateway event brokers). They also provide plans that configure policies such as event retention.
- Application Registrations represent a developer application. When a developer requests access, for example, by attempting to subscribe to an Event API Product, an access request must be associated with the Application Registration.
The following diagram illustrates the object model and the core entities:
![diagram showing the object model described in the surrounding text](https://files.readme.io/e8a3070-gs-apim-concepts.png)
Event API Products are managed and maintained using Event Portal. Application Registrations are created and managed by the API client - for example, a developer portal or API Marketplace where a developer registers their API access requests.
Event Portal Prerequisites
To make Event API Products available, some steps must be completed in the Event Portal Runtime Event Manager and Designer tools:
- Configure PubSub+ event brokers in Runtime Event Manager to use Event API Products.
- Make Event API Products "publicly available" so they are visible in the API.
Configure Solace Event Brokers in Runtime Event Manager
This section highlights the relevant actions required for the API. For more details see the Runtime Event Manager product documentation.
You must have a suitable event broker set up in a modeled event mesh to associate Event API Products with an environment and the event broker:
- Create a new or use an existing modeled event mesh.
- Navigate to the modeled event mesh and select the Event Broker Connections tab.
- If the intended event broker is not listed, add an event broker to the modeled event mesh.
- Verify or add the event broker configuration details.
Create or Use an Existing Modeled Event Mesh
See the product documentation for details
Navigate to the Modeled Event Mesh and Select the Event Broker Connections Tab
![Screenshot showing the options described in the surrounding text.](https://files.readme.io/cb5b8df-426e345-image.png)
Connect an Event Broker
If the intended event broker is not listed, see Adding an Event Broker to a Modeled Event Mesh.
Verify the Event Broker Configuration
If the intended event broker is already in the modeled event mesh, select the event broker and click View Connection Details. Verify all connection details for the event broker on the Management and Messaging tabs.
For more information about setting event broker configuration details, see Managing Model Event Brokers.
The Management settings must be fully provided. For PubSub+ event brokers (Solace event brokers) that are not managed in PubSub+ Cloud, you need to provide an appropriate password to the API. For more information, see Configuring Event Broker Secrets.
![Screenshot showing the options described in the surrounding text.](https://files.readme.io/9c66202-35979d2-image.png)
On the Messaging tab, set the Host Name and add all the protocols that you want to expose in Event API Products.
![Screenshot showing the options described in the surrounding text.](https://files.readme.io/584f483-26218c0-image.png)
Make Event API Products Publicly Available
Only publicly available Event API Products are visible in the API. The following conditions must apply (see the illustration below):
- The Event API Product must be "shared".
- The version must be in Released state.
- An environment and event broker must be associated with the version.
- At least one plan must be defined.
- The version must be marked as "publicly available".
![Screenshot showing the options described in the surrounding text.](https://files.readme.io/2ddad59-ca4d23d-image.png)
Interacting with the API
Now you can interact with the API:
- API authentication
- Obtaining available Event API Products
- Continue a simple end-to-end walkthrough
- Filtering Event API Products
- Filter Event API Products on custom attributes
API Authentication
To use the API Management, you require an API token that you generate in the PubSub+ Cloud Console. For more information about creating and managing API tokens, see Authentication.
The API token you create must have at least the following permissions. To create an API token, see Steps for Creating an API Token.
Location on the API Token Management Page | Permissions | API Token Permission |
---|---|---|
Mission Control > My Service | Allow access to Mission Control | mission_control:access
|
Get My Services with Management Credentials | services:get:self
|
|
Mission Control > Organization Services | Create / Update / Delete Client Profiles | service_requests:post:client_profile
|
Get Services with Management Credentials | services:get
|
|
Event Portal 2.0 > Runtime Event Manager | Get Environment in Event Portal | ep_environment:get:*
|
Get Event Broker in Event Portal | modeled_event_broker:get:*
|
|
Read any Modeled Event Mesh | modeled_event_mesh:get:*
|
|
Event Portal 2.0 > API Management/DevPortal | Create, update, or delete published event API products and their underlying resources | apim_event_api_product:*:*
|
Get published event API products and their underlying resources (in permission set | apim_event_api_product:get:*
|
|
Event Portal | Read any Application Domain | application_domain:get:*
|
Access to Event Portal Designer | event_designer:access
|
Configuring Event Broker Secrets
For PubSub+ event brokers that are not managed in PubSub+ Cloud, you need to provide an appropriate password to the API.
Looking up the Gateway Event Broker Id
You can look up the id
of an event broker using the (Early Access) Returns a list of all available Gateway Event Brokers resource:
-
Provide a valid API token in the HTTP Authorization header. See Create an API Token for more information
This call returns a list of gateway event brokers that are defined in the Event Portal Runtime Manager account associated with the provided API token. The id property of the object can be used to retrieve a detail view of a gateway event broker.
-
Take note of the gateway event broker service
id
that you need to set a password for.
curl --request GET
--url <https://apim-production-api.solace.cloud/api/v2/apim/gateways>
--header 'accept: application/json'
--header 'authorization: Bearer {apiToken}
You can set the password using the setgatewaysecret resource. The password is securely encrypted and stored in PubSub+ Cloud.
Setting Up the Event Broker Id
Set {apiToken}
to provide a valid PubSub+ Cloud API token in the HTTP Authorization header (see above).
Set {eventBrokerId}
to the id
you identified in the previous step.
Set {password}
to the SEMP password of the event broker service.
Replace {eventBrokerId}
with the id
of the event broker service and {password}
with the SEMP password of the event broker service:
curl --request PATCH
--url <https://apim-production-api.solace.cloud/api/v2/apim/gateways/{eventBrokerId}>
--header 'accept: application/json'
--header 'authorization: Bearer {apiToken}
--header 'content-type: application/json'
--data '{"secret":"{password}"}'
Get Event API Products
Let's look at the first API call and explore the main elements of an Event API Product.
- You must provide a valid API token in the HTTP Authorization header.
- The call returns a list of Event API Products that are publicly available in the Event Portal account associated with the provided API token.
Theid
property of the object can be used to retrieve a detail view and to call sub-resources of Event API Products, such as plans or attributes. - Plans are embedded in the Event API Product response. Plans represent the service-level agreements (SLAs) or tiers offered for subscriptions created by developers.
- The APIs array contains the Event APIs that are part of the Event API Product.
curl --request GET \
--url https://apim-devportal-api.solace-labs.io/api/v2/apim/eventApiProducts \
--header 'accept: application/json' \
--header 'authorization: Bearer <<user>>'
{
"data": [
{
"plans": [
{
"id": "8a0g3o0prdf",
"name": "silver",
"solaceClassOfServicePolicy": {
"id": "x1c1zh539xg",
"messageDeliveryMode": "guaranteed",
"accessType": "exclusive",
"maximumTimeToLive": 1,
"queueType": "single",
"maxMsgSpoolUsage": 1
}
},
{
"id": "lsw67j8cy26",
"name": "bronze",
"solaceClassOfServicePolicy": {
"id": "t9vhjuizng4",
"messageDeliveryMode": "guaranteed",
"accessType": "exclusive",
"maximumTimeToLive": 1,
"queueType": "single",
"maxMsgSpoolUsage": 1
}
}
],
"apis": [
{
"id": "29591g18w8q",
"version": "1.0.0",
"description": "BUS1006",
"displayName": "BUS1006",
"name": "BUS1006",
"customAttributes": []
}
],
"apiParameters": [
{
"name": "REFERENCE",
"dataType": "string",
"parameterType": "unbounded"
}
]
"createdTime": 1693576372483,
"updatedTime": 1693576420187,
"createdBy": "3e2ocmx105",
"changedBy": "3e2ocmx105",
"id": "kils37cwlkz",
"name": "Asapio BUS1006",
"applicationDomainId": "bpgli1jzier",
"applicationDomainName": "asapio/consumers",
"approvalType": "automatic",
"brokerType": "solace",
"description": "BUS1006 - new version",
"version": "1.7.0",
"displayName": "1.7.0-BUS1006",
"state": "RELEASED",
"solaceMessagingServices": [
{
"solaceCloudMessagingServiceId": "dr6uq5q8gjj",
"id": "f5ug1291p2g",
"messagingServiceId": "wgex5k3ov3h",
"messagingServiceName": "APIM-GW-DEV",
"supportedProtocols": [
"smfc",
"smf",
"smfs",
"amqp",
"amqps",
"mqtt",
"secure-mqtt",
"mqttws",
"secure-mqttws",
"http",
"https"
],
"environmentName": "asapio",
"eventMeshName": "asapio"
}
],
"customAttributes": [
{
"name": "PUBLISH_DESTINATIONS",
"value": "ep-developer-portal"
}
],
"attributes": [],
}
],
"meta": {
"pagination": {
"pageNumber": 1,
"nextPage": null,
"totalPages": 1,
"count": 1,
"pageSize": 20
}
}
}