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:

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

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.

On the Messaging tab, set the Host Name and add all the protocols that you want to expose in Event API Products.

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".

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 PubSub+ user account that you are using to create the API token must have the following roles:

• Event Portal Manager for full access to Event Portal
• Mission Control Manager for full access to Mission Control

If your user account does not have the required roles, contact an administrator for your PubSub+ account to get the appropriate roles assigned. Alternatively, you can have another user with the required roles to create an API token for you. To create an API token, see Steps for Creating an API Token.

The API token you create must have at least the following permissions as shown in the following table.

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:

1. 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.

2. 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.

1. You must provide a valid API token in the HTTP Authorization header.
2. The call returns a list of Event API Products that are publicly available in the Event Portal account associated with the provided API token.
   The id 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.
3. Plans are embedded in the Event API Product response. Plans represent the service-level agreements (SLAs) or tiers offered for subscriptions created by developers.
4. 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
        }
    }
}