API Reference

API Walkthrough

This guide walks you through an end to end scenario of the main API resources

Let's look at the main resources you need to implement an end to end integration form obtaining Event API Products to registering Event API access:

  1. Obtain Event API Products (EAP) - you can check Getting Started with Event Portal's APIM/DevPortal API how this is done
  2. Obtain details of an EAP
  3. Obtain the Async API for a specific EAP and Plan
  4. Create an Application Registration
  5. Add an Access Request for the EAP and Plan
  6. Retrieve the status of the Access Request to track configuration status

📘

Take note of one of the Event API Product id you obtained in the Getting Started with Event Portal's APIM/DevPortal API guide.

Obtain Details of an EAP

Using the id of one of the EAPs you retrieved in the Getting Started with Event Portal's APIM/DevPortal API guide - obtain the details replacing eventApPiProductId with the id.

The response contains:

  • Plans (plans array) - these represent the SLAs or tiers offered for subscriptions created by developers.
  • APIs (apis array) contains the Event APIs that are included in the Event API Product.
curl --location 'https://apim-devportal-api.solace-labs.io/api/v2/apim/eventApiProducts/{eventApPiProductId}' \
--header 'Authorization: Bearer <<api-token>>'
{
    "data": {
        "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",
        "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
                }
            }
        ],
        "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": [],
        "apis": [
            {
                "id": "29591g18w8q",
                "version": "1.0.0",
                "description": "BUS1006",
                "displayName": "BUS1006",
                "name": "BUS1006",
                "customAttributes": []
            }
        ],
        "apiParameters": [
            {
                "name": "REFERENCE",
                "dataType": "string",
                "parameterType": "unbounded"
            }
        ]
    },
    "meta": {}
}

📘

Take note of a Plan and API id to use in the following calls

Obtain the Async API for a specific EAP and Plan

You will likely want to present API documentation to developers and allow them to download AsyncAPI documents for use in their development process.

Here is how you obtain an Async API:

  1. Set {eventApiProductId}: Use the id of the required Event API Product
  2. Set {planId}: Use the id of the Plan you want to apply to the Async API. The Event API Product you retrieved previously contains all the Plans that are available. The Async API contains protocol bindings information such as message delivery mode, queue size, event retention policy in accordance with the Plan you reference
  3. Set {eventApiId}: Finally set the eventApiId - available APIs are listed on the apiselement of the Event API Product, use the id of any of the APIs as required
curl --location 'https://apim-devportal-api.solace-labs.io/api/v2/apim/eventApiProducts/{eventApiProductId}/plans/{planId}/eventApis/{eventApiId}' \
--header 'Authorization: Bearer <<api-token>>'
{
    "components": {
        "schemas": {
            "Z_BP_ADDR": {
                "x-ep-schema-version": "1.0.0",
                "x-ep-schema-version-id": "vml46iq7gjg",
                "$schema": "http://json-schema.org/draft-07/schema",
                "description": "Description.",
                "x-ep-schema-state-name": "RELEASED",
                "x-ep-schema-name": "Z_BP_ADDR",
                "title": "Z_BP_ADDR",
                "type": "object",
                "x-ep-application-domain-id": "82z4evtb5rl",
                "x-ep-schema-version-displayname": "Z_BP_ADDR",
                "x-ep-shared": "true",
                "x-ep-application-domain-name": "asapio/assets",
                "x-ep-schema-state-id": "2",
                "x-ep-schema-id": "jr3if9m436q",
                "properties": {
                    "BUT000": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "PARTNER": {
                                    "description": "Business Partner Number",
                                    "type": "string",
                                    "maxLength": 10,
                                    "x-parser-schema-id": "<anonymous-schema-3>"
                                },
                                "NAME_LAST": {
                                    "description": "Last name of business partner (person)",
                                    "type": "string",
                                    "maxLength": 40,
                                    "x-parser-schema-id": "<anonymous-schema-4>"
                                },
                                "BUT020": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "ADDRNUMBER": {
                                                "description": "Address number",
                                                "type": "string",
                                                "maxLength": 10,
                                                "x-parser-schema-id": "<anonymous-schema-7>"
                                            },
                                            "ADRC": {
                                                "type": "array",
                                                "items": {
                                                    "type": "object",
                                                    "properties": {
                                                        "NATION": {
                                                            "description": "Version ID for International Addresses",
                                                            "type": "string",
                                                            "maxLength": 1,
                                                            "x-parser-schema-id": "<anonymous-schema-10>"
                                                        },
                                                        "DATE_FROM": {
                                                            "description": "Valid-from date - in current Release only 00010101 possible",
                                                            "type": "string",
                                                            "maxLength": 10,
                                                            "x-parser-schema-id": "<anonymous-schema-11>"
                                                        },
                                                        "CITY1": {
                                                            "description": "City",
                                                            "type": "string",
                                                            "maxLength": 40,
                                                            "x-parser-schema-id": "<anonymous-schema-12>"
                                                        },
                                                        "COUNTRY": {
                                                            "description": "Country Key",
                                                            "type": "string",
                                                            "maxLength": 3,
                                                            "x-parser-schema-id": "<anonymous-schema-13>"
                                                        },
                                                        "POST_CODE1": {
                                                            "description": "City postal code",
                                                            "type": "string",
                                                            "maxLength": 10,
                                                            "x-parser-schema-id": "<anonymous-schema-14>"
                                                        },
                                                        "HOUSE_NUM1": {
                                                            "description": "House Number",
                                                            "type": "string",
                                                            "maxLength": 10,
                                                            "x-parser-schema-id": "<anonymous-schema-15>"
                                                        },
                                                        "STREET": {
                                                            "description": "Street",
                                                            "type": "string",
                                                            "maxLength": 60,
                                                            "x-parser-schema-id": "<anonymous-schema-16>"
                                                        }
                                                    },
                                                    "required": [
                                                        "From",
                                                        "Addr.Vers."
                                                    ],
                                                    "x-parser-schema-id": "<anonymous-schema-9>"
                                                },
                                                "x-parser-schema-id": "<anonymous-schema-8>"
                                            }
                                        },
                                        "required": [
                                            "Addr. no."
                                        ],
                                        "x-parser-schema-id": "<anonymous-schema-6>"
                                    },
                                    "x-parser-schema-id": "<anonymous-schema-5>"
                                },
                                "TYPE": {
                                    "description": "Business partner category",
                                    "type": "string",
                                    "maxLength": 1,
                                    "enum": [
                                        "1",
                                        "2",
                                        "3"
                                    ],
                                    "x-parser-schema-id": "<anonymous-schema-17>"
                                },
                                "CLIENT": {
                                    "description": "Client",
                                    "type": "string",
                                    "maxLength": 3,
                                    "x-parser-schema-id": "<anonymous-schema-18>"
                                },
                                "NAME_FIRST": {
                                    "description": "First name of business partner (person)",
                                    "type": "string",
                                    "maxLength": 40,
                                    "x-parser-schema-id": "<anonymous-schema-19>"
                                }
                            },
                            "required": [
                                "Client",
                                "Partner"
                            ],
                            "x-parser-schema-id": "<anonymous-schema-2>"
                        },
                        "x-parser-schema-id": "<anonymous-schema-1>"
                    }
                },
                "$id": "http://example.com/example.json",
                "x-parser-schema-id": "Z_BP_ADDR"
            }
        },
        "messages": {
            "BP_CHANGE": {
                "x-ep-event-id": "bukyatfi4wu",
                "x-ep-custom-attr-PUBLISH_DESTINATIONS": "ep-developer-portal",
                "x-ep-event-version-displayname": "BP_CHANGE",
                "description": "",
                "x-ep-application-domain-id": "82z4evtb5rl",
                "schemaFormat": "application/vnd.aai.asyncapi;version=2.5.0",
                "x-ep-event-state-name": "RELEASED",
                "x-ep-shared": "true",
                "x-ep-application-domain-name": "asapio/assets",
                "x-ep-event-version-id": "adm4yhqiiaj",
                "payload": {
                    "x-ep-schema-version": "1.0.0",
                    "x-ep-schema-version-id": "vml46iq7gjg",
                    "$schema": "http://json-schema.org/draft-07/schema",
                    "description": "Description.",
                    "x-ep-schema-state-name": "RELEASED",
                    "x-ep-schema-name": "Z_BP_ADDR",
                    "title": "Z_BP_ADDR",
                    "type": "object",
                    "x-ep-application-domain-id": "82z4evtb5rl",
                    "x-ep-schema-version-displayname": "Z_BP_ADDR",
                    "x-ep-shared": "true",
                    "x-ep-application-domain-name": "asapio/assets",
                    "x-ep-schema-state-id": "2",
                    "x-ep-schema-id": "jr3if9m436q",
                    "properties": {
                        "BUT000": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "PARTNER": {
                                        "description": "Business Partner Number",
                                        "type": "string",
                                        "maxLength": 10,
                                        "x-parser-schema-id": "<anonymous-schema-3>"
                                    },
                                    "NAME_LAST": {
                                        "description": "Last name of business partner (person)",
                                        "type": "string",
                                        "maxLength": 40,
                                        "x-parser-schema-id": "<anonymous-schema-4>"
                                    },
                                    "BUT020": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "ADDRNUMBER": {
                                                    "description": "Address number",
                                                    "type": "string",
                                                    "maxLength": 10,
                                                    "x-parser-schema-id": "<anonymous-schema-7>"
                                                },
                                                "ADRC": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "NATION": {
                                                                "description": "Version ID for International Addresses",
                                                                "type": "string",
                                                                "maxLength": 1,
                                                                "x-parser-schema-id": "<anonymous-schema-10>"
                                                            },
                                                            "DATE_FROM": {
                                                                "description": "Valid-from date - in current Release only 00010101 possible",
                                                                "type": "string",
                                                                "maxLength": 10,
                                                                "x-parser-schema-id": "<anonymous-schema-11>"
                                                            },
                                                            "CITY1": {
                                                                "description": "City",
                                                                "type": "string",
                                                                "maxLength": 40,
                                                                "x-parser-schema-id": "<anonymous-schema-12>"
                                                            },
                                                            "COUNTRY": {
                                                                "description": "Country Key",
                                                                "type": "string",
                                                                "maxLength": 3,
                                                                "x-parser-schema-id": "<anonymous-schema-13>"
                                                            },
                                                            "POST_CODE1": {
                                                                "description": "City postal code",
                                                                "type": "string",
                                                                "maxLength": 10,
                                                                "x-parser-schema-id": "<anonymous-schema-14>"
                                                            },
                                                            "HOUSE_NUM1": {
                                                                "description": "House Number",
                                                                "type": "string",
                                                                "maxLength": 10,
                                                                "x-parser-schema-id": "<anonymous-schema-15>"
                                                            },
                                                            "STREET": {
                                                                "description": "Street",
                                                                "type": "string",
                                                                "maxLength": 60,
                                                                "x-parser-schema-id": "<anonymous-schema-16>"
                                                            }
                                                        },
                                                        "required": [
                                                            "From",
                                                            "Addr.Vers."
                                                        ],
                                                        "x-parser-schema-id": "<anonymous-schema-9>"
                                                    },
                                                    "x-parser-schema-id": "<anonymous-schema-8>"
                                                }
                                            },
                                            "required": [
                                                "Addr. no."
                                            ],
                                            "x-parser-schema-id": "<anonymous-schema-6>"
                                        },
                                        "x-parser-schema-id": "<anonymous-schema-5>"
                                    },
                                    "TYPE": {
                                        "description": "Business partner category",
                                        "type": "string",
                                        "maxLength": 1,
                                        "enum": [
                                            "1",
                                            "2",
                                            "3"
                                        ],
                                        "x-parser-schema-id": "<anonymous-schema-17>"
                                    },
                                    "CLIENT": {
                                        "description": "Client",
                                        "type": "string",
                                        "maxLength": 3,
                                        "x-parser-schema-id": "<anonymous-schema-18>"
                                    },
                                    "NAME_FIRST": {
                                        "description": "First name of business partner (person)",
                                        "type": "string",
                                        "maxLength": 40,
                                        "x-parser-schema-id": "<anonymous-schema-19>"
                                    }
                                },
                                "required": [
                                    "Client",
                                    "Partner"
                                ],
                                "x-parser-schema-id": "<anonymous-schema-2>"
                            },
                            "x-parser-schema-id": "<anonymous-schema-1>"
                        }
                    },
                    "$id": "http://example.com/example.json",
                    "x-parser-schema-id": "Z_BP_ADDR"
                },
                "x-ep-event-version": "1.0.0",
                "x-ep-event-name": "BP_CHANGE",
                "contentType": "application/json",
                "x-ep-event-state-id": "2",
                "x-parser-original-schema-format": "application/vnd.aai.asyncapi+json;version=2.0.0",
                "x-parser-original-payload": {
                    "x-ep-schema-version": "1.0.0",
                    "x-ep-schema-version-id": "vml46iq7gjg",
                    "$schema": "http://json-schema.org/draft-07/schema",
                    "description": "Description.",
                    "x-ep-schema-state-name": "RELEASED",
                    "x-ep-schema-name": "Z_BP_ADDR",
                    "title": "Z_BP_ADDR",
                    "type": "object",
                    "x-ep-application-domain-id": "82z4evtb5rl",
                    "x-ep-schema-version-displayname": "Z_BP_ADDR",
                    "x-ep-shared": "true",
                    "x-ep-application-domain-name": "asapio/assets",
                    "x-ep-schema-state-id": "2",
                    "x-ep-schema-id": "jr3if9m436q",
                    "properties": {
                        "BUT000": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "PARTNER": {
                                        "description": "Business Partner Number",
                                        "type": "string",
                                        "maxLength": 10
                                    },
                                    "NAME_LAST": {
                                        "description": "Last name of business partner (person)",
                                        "type": "string",
                                        "maxLength": 40
                                    },
                                    "BUT020": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "ADDRNUMBER": {
                                                    "description": "Address number",
                                                    "type": "string",
                                                    "maxLength": 10
                                                },
                                                "ADRC": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "NATION": {
                                                                "description": "Version ID for International Addresses",
                                                                "type": "string",
                                                                "maxLength": 1
                                                            },
                                                            "DATE_FROM": {
                                                                "description": "Valid-from date - in current Release only 00010101 possible",
                                                                "type": "string",
                                                                "maxLength": 10
                                                            },
                                                            "CITY1": {
                                                                "description": "City",
                                                                "type": "string",
                                                                "maxLength": 40
                                                            },
                                                            "COUNTRY": {
                                                                "description": "Country Key",
                                                                "type": "string",
                                                                "maxLength": 3
                                                            },
                                                            "POST_CODE1": {
                                                                "description": "City postal code",
                                                                "type": "string",
                                                                "maxLength": 10
                                                            },
                                                            "HOUSE_NUM1": {
                                                                "description": "House Number",
                                                                "type": "string",
                                                                "maxLength": 10
                                                            },
                                                            "STREET": {
                                                                "description": "Street",
                                                                "type": "string",
                                                                "maxLength": 60
                                                            }
                                                        },
                                                        "required": [
                                                            "From",
                                                            "Addr.Vers."
                                                        ]
                                                    }
                                                }
                                            },
                                            "required": [
                                                "Addr. no."
                                            ]
                                        }
                                    },
                                    "TYPE": {
                                        "description": "Business partner category",
                                        "type": "string",
                                        "maxLength": 1,
                                        "enum": [
                                            "1",
                                            "2",
                                            "3"
                                        ]
                                    },
                                    "CLIENT": {
                                        "description": "Client",
                                        "type": "string",
                                        "maxLength": 3
                                    },
                                    "NAME_FIRST": {
                                        "description": "First name of business partner (person)",
                                        "type": "string",
                                        "maxLength": 40
                                    }
                                },
                                "required": [
                                    "Client",
                                    "Partner"
                                ]
                            }
                        }
                    },
                    "$id": "http://example.com/example.json"
                },
                "x-parser-message-parsed": true,
                "x-parser-message-name": "BP_CHANGE"
            }
        }
    },
    "servers": {
        "apim-gw-dev-rests": {
            "protocol": "rests",
            "variables": {
                "port": {
                    "enum": [
                        "9443"
                    ]
                }
            },
            "bindings": {},
            "protocolVersion": "1.1.0",
            "url": "https://mr-connection-6mdexb3glmb.messaging.solace.cloud:9443"
        },
        "apim-gw-dev-secure-mqttws": {
            "protocol": "secure-mqttws",
            "variables": {
                "port": {
                    "enum": [
                        "8443"
                    ]
                }
            },
            "bindings": {},
            "protocolVersion": "3.1.1",
            "url": "wss://mr-connection-6mdexb3glmb.messaging.solace.cloud:8443"
        },
        "apim-gw-dev-smfs": {
            "protocol": "smfs",
            "variables": {
                "port": {
                    "enum": [
                        "55443"
                    ]
                }
            },
            "bindings": {},
            "protocolVersion": "1.0.0",
            "url": "tcps://mr-connection-6mdexb3glmb.messaging.solace.cloud:55443"
        },
        "apim-gw-dev-smfc": {
            "protocol": "smfc",
            "variables": {
                "port": {
                    "enum": [
                        "55003"
                    ]
                }
            },
            "bindings": {},
            "protocolVersion": "1.0.0",
            "url": "tcps://mr-connection-6mdexb3glmb.messaging.solace.cloud:55003"
        },
        "apim-gw-dev-secure-mqtt": {
            "protocol": "secure-mqtt",
            "variables": {
                "port": {
                    "enum": [
                        "8883"
                    ]
                }
            },
            "bindings": {},
            "protocolVersion": "3.1.1",
            "url": "ssl://mr-connection-6mdexb3glmb.messaging.solace.cloud:8883"
        },
        "apim-gw-dev-amqps": {
            "protocol": "amqps",
            "variables": {
                "port": {
                    "enum": [
                        "5671"
                    ]
                }
            },
            "bindings": {},
            "protocolVersion": "1.0.0",
            "url": "amqps://mr-connection-6mdexb3glmb.messaging.solace.cloud:5671"
        },
        "apim-gw-dev-amqp": {
            "protocol": "amqp",
            "variables": {
                "port": {
                    "enum": [
                        "5672"
                    ]
                }
            },
            "bindings": {},
            "protocolVersion": "1.0.0",
            "url": "amqp://mr-connection-6mdexb3glmb.messaging.solace.cloud:5672"
        },
        "apim-gw-dev-rest": {
            "protocol": "rest",
            "variables": {
                "port": {
                    "enum": [
                        "9000"
                    ]
                }
            },
            "bindings": {},
            "protocolVersion": "1.1.0",
            "url": "http://mr-connection-6mdexb3glmb.messaging.solace.cloud:9000"
        },
        "apim-gw-dev-mqtt": {
            "protocol": "mqtt",
            "variables": {
                "port": {
                    "enum": [
                        "1883"
                    ]
                }
            },
            "bindings": {},
            "protocolVersion": "3.1.1",
            "url": "tcp://mr-connection-6mdexb3glmb.messaging.solace.cloud:1883"
        },
        "apim-gw-dev-mqttws": {
            "protocol": "mqttws",
            "variables": {
                "port": {
                    "enum": [
                        "8000"
                    ]
                }
            },
            "bindings": {},
            "protocolVersion": "3.1.1",
            "url": "ws://mr-connection-6mdexb3glmb.messaging.solace.cloud:8000"
        },
        "apim-gw-dev-smf": {
            "protocol": "smf",
            "variables": {
                "port": {
                    "enum": [
                        "55555"
                    ]
                }
            },
            "bindings": {},
            "protocolVersion": "1.0.0",
            "url": "tcp://mr-connection-6mdexb3glmb.messaging.solace.cloud:55555"
        }
    },
    "channels": {
        "sap_demo/BUS1006/sap-bo-data/update/json/v1/asadev/emptyType/ERD100/{REFERENCE}": {
            "publish": {
                "bindings": {
                    "rest": {
                        "method": "POST",
                        "type": "request",
                        "bindingVersion": "0.1.0"
                    },
                    "mqtt": {
                        "qos": 1,
                        "bindingVersion": "0.1.0"
                    },
                    "solace": {
                        "destinations": [
                            {
                                "destinationType": "queue",
                                "queue": {
                                    "accessType": "exclusive",
                                    "maxTtl": "1",
                                    "maxMsgSpoolUsage": "1",
                                    "topicSubscriptions": []
                                }
                            }
                        ],
                        "bindingVersion": "0.3.0"
                    }
                },
                "message": {
                    "x-ep-event-id": "bukyatfi4wu",
                    "x-ep-custom-attr-PUBLISH_DESTINATIONS": "ep-developer-portal",
                    "x-ep-event-version-displayname": "BP_CHANGE",
                    "description": "",
                    "x-ep-application-domain-id": "82z4evtb5rl",
                    "schemaFormat": "application/vnd.aai.asyncapi;version=2.5.0",
                    "x-ep-event-state-name": "RELEASED",
                    "x-ep-shared": "true",
                    "x-ep-application-domain-name": "asapio/assets",
                    "x-ep-event-version-id": "adm4yhqiiaj",
                    "payload": {
                        "x-ep-schema-version": "1.0.0",
                        "x-ep-schema-version-id": "vml46iq7gjg",
                        "$schema": "http://json-schema.org/draft-07/schema",
                        "description": "Description.",
                        "x-ep-schema-state-name": "RELEASED",
                        "x-ep-schema-name": "Z_BP_ADDR",
                        "title": "Z_BP_ADDR",
                        "type": "object",
                        "x-ep-application-domain-id": "82z4evtb5rl",
                        "x-ep-schema-version-displayname": "Z_BP_ADDR",
                        "x-ep-shared": "true",
                        "x-ep-application-domain-name": "asapio/assets",
                        "x-ep-schema-state-id": "2",
                        "x-ep-schema-id": "jr3if9m436q",
                        "properties": {
                            "BUT000": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "PARTNER": {
                                            "description": "Business Partner Number",
                                            "type": "string",
                                            "maxLength": 10,
                                            "x-parser-schema-id": "<anonymous-schema-3>"
                                        },
                                        "NAME_LAST": {
                                            "description": "Last name of business partner (person)",
                                            "type": "string",
                                            "maxLength": 40,
                                            "x-parser-schema-id": "<anonymous-schema-4>"
                                        },
                                        "BUT020": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "ADDRNUMBER": {
                                                        "description": "Address number",
                                                        "type": "string",
                                                        "maxLength": 10,
                                                        "x-parser-schema-id": "<anonymous-schema-7>"
                                                    },
                                                    "ADRC": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "object",
                                                            "properties": {
                                                                "NATION": {
                                                                    "description": "Version ID for International Addresses",
                                                                    "type": "string",
                                                                    "maxLength": 1,
                                                                    "x-parser-schema-id": "<anonymous-schema-10>"
                                                                },
                                                                "DATE_FROM": {
                                                                    "description": "Valid-from date - in current Release only 00010101 possible",
                                                                    "type": "string",
                                                                    "maxLength": 10,
                                                                    "x-parser-schema-id": "<anonymous-schema-11>"
                                                                },
                                                                "CITY1": {
                                                                    "description": "City",
                                                                    "type": "string",
                                                                    "maxLength": 40,
                                                                    "x-parser-schema-id": "<anonymous-schema-12>"
                                                                },
                                                                "COUNTRY": {
                                                                    "description": "Country Key",
                                                                    "type": "string",
                                                                    "maxLength": 3,
                                                                    "x-parser-schema-id": "<anonymous-schema-13>"
                                                                },
                                                                "POST_CODE1": {
                                                                    "description": "City postal code",
                                                                    "type": "string",
                                                                    "maxLength": 10,
                                                                    "x-parser-schema-id": "<anonymous-schema-14>"
                                                                },
                                                                "HOUSE_NUM1": {
                                                                    "description": "House Number",
                                                                    "type": "string",
                                                                    "maxLength": 10,
                                                                    "x-parser-schema-id": "<anonymous-schema-15>"
                                                                },
                                                                "STREET": {
                                                                    "description": "Street",
                                                                    "type": "string",
                                                                    "maxLength": 60,
                                                                    "x-parser-schema-id": "<anonymous-schema-16>"
                                                                }
                                                            },
                                                            "required": [
                                                                "From",
                                                                "Addr.Vers."
                                                            ],
                                                            "x-parser-schema-id": "<anonymous-schema-9>"
                                                        },
                                                        "x-parser-schema-id": "<anonymous-schema-8>"
                                                    }
                                                },
                                                "required": [
                                                    "Addr. no."
                                                ],
                                                "x-parser-schema-id": "<anonymous-schema-6>"
                                            },
                                            "x-parser-schema-id": "<anonymous-schema-5>"
                                        },
                                        "TYPE": {
                                            "description": "Business partner category",
                                            "type": "string",
                                            "maxLength": 1,
                                            "enum": [
                                                "1",
                                                "2",
                                                "3"
                                            ],
                                            "x-parser-schema-id": "<anonymous-schema-17>"
                                        },
                                        "CLIENT": {
                                            "description": "Client",
                                            "type": "string",
                                            "maxLength": 3,
                                            "x-parser-schema-id": "<anonymous-schema-18>"
                                        },
                                        "NAME_FIRST": {
                                            "description": "First name of business partner (person)",
                                            "type": "string",
                                            "maxLength": 40,
                                            "x-parser-schema-id": "<anonymous-schema-19>"
                                        }
                                    },
                                    "required": [
                                        "Client",
                                        "Partner"
                                    ],
                                    "x-parser-schema-id": "<anonymous-schema-2>"
                                },
                                "x-parser-schema-id": "<anonymous-schema-1>"
                            }
                        },
                        "$id": "http://example.com/example.json",
                        "x-parser-schema-id": "Z_BP_ADDR"
                    },
                    "x-ep-event-version": "1.0.0",
                    "x-ep-event-name": "BP_CHANGE",
                    "contentType": "application/json",
                    "x-ep-event-state-id": "2",
                    "x-parser-original-schema-format": "application/vnd.aai.asyncapi+json;version=2.0.0",
                    "x-parser-original-payload": {
                        "x-ep-schema-version": "1.0.0",
                        "x-ep-schema-version-id": "vml46iq7gjg",
                        "$schema": "http://json-schema.org/draft-07/schema",
                        "description": "Description.",
                        "x-ep-schema-state-name": "RELEASED",
                        "x-ep-schema-name": "Z_BP_ADDR",
                        "title": "Z_BP_ADDR",
                        "type": "object",
                        "x-ep-application-domain-id": "82z4evtb5rl",
                        "x-ep-schema-version-displayname": "Z_BP_ADDR",
                        "x-ep-shared": "true",
                        "x-ep-application-domain-name": "asapio/assets",
                        "x-ep-schema-state-id": "2",
                        "x-ep-schema-id": "jr3if9m436q",
                        "properties": {
                            "BUT000": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "PARTNER": {
                                            "description": "Business Partner Number",
                                            "type": "string",
                                            "maxLength": 10
                                        },
                                        "NAME_LAST": {
                                            "description": "Last name of business partner (person)",
                                            "type": "string",
                                            "maxLength": 40
                                        },
                                        "BUT020": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "ADDRNUMBER": {
                                                        "description": "Address number",
                                                        "type": "string",
                                                        "maxLength": 10
                                                    },
                                                    "ADRC": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "object",
                                                            "properties": {
                                                                "NATION": {
                                                                    "description": "Version ID for International Addresses",
                                                                    "type": "string",
                                                                    "maxLength": 1
                                                                },
                                                                "DATE_FROM": {
                                                                    "description": "Valid-from date - in current Release only 00010101 possible",
                                                                    "type": "string",
                                                                    "maxLength": 10
                                                                },
                                                                "CITY1": {
                                                                    "description": "City",
                                                                    "type": "string",
                                                                    "maxLength": 40
                                                                },
                                                                "COUNTRY": {
                                                                    "description": "Country Key",
                                                                    "type": "string",
                                                                    "maxLength": 3
                                                                },
                                                                "POST_CODE1": {
                                                                    "description": "City postal code",
                                                                    "type": "string",
                                                                    "maxLength": 10
                                                                },
                                                                "HOUSE_NUM1": {
                                                                    "description": "House Number",
                                                                    "type": "string",
                                                                    "maxLength": 10
                                                                },
                                                                "STREET": {
                                                                    "description": "Street",
                                                                    "type": "string",
                                                                    "maxLength": 60
                                                                }
                                                            },
                                                            "required": [
                                                                "From",
                                                                "Addr.Vers."
                                                            ]
                                                        }
                                                    }
                                                },
                                                "required": [
                                                    "Addr. no."
                                                ]
                                            }
                                        },
                                        "TYPE": {
                                            "description": "Business partner category",
                                            "type": "string",
                                            "maxLength": 1,
                                            "enum": [
                                                "1",
                                                "2",
                                                "3"
                                            ]
                                        },
                                        "CLIENT": {
                                            "description": "Client",
                                            "type": "string",
                                            "maxLength": 3
                                        },
                                        "NAME_FIRST": {
                                            "description": "First name of business partner (person)",
                                            "type": "string",
                                            "maxLength": 40
                                        }
                                    },
                                    "required": [
                                        "Client",
                                        "Partner"
                                    ]
                                }
                            }
                        },
                        "$id": "http://example.com/example.json"
                    },
                    "x-parser-message-parsed": true,
                    "x-parser-message-name": "BP_CHANGE"
                }
            },
            "parameters": {
                "REFERENCE": {
                    "schema": {
                        "type": "string",
                        "x-parser-schema-id": "REFERENCE"
                    },
                    "x-ep-parameter-name": "REFERENCE"
                }
            }
        }
    },
    "asyncapi": "2.5.0",
    "info": {
        "x-ep-event-api-product-version-id": "ghv5ovh368a",
        "x-ep-event-api-id": "azd2w9052o3",
        "x-ep-event-api-product-version": "1.7.0",
        "description": "BUS1006",
        "x-ep-state-name": "RELEASED",
        "title": "BUS1006",
        "x-ep-application-domain-id": "bpgli1jzier",
        "version": "1.0.0",
        "x-ep-event-api-product-id": "kils37cwlkz",
        "x-ep-event-api-version-id": "29591g18w8q",
        "x-ep-application-domain-name": "asapio/consumers",
        "x-ep-shared": "true",
        "x-ep-event-api-version": "1.0.0",
        "x-ep-event-api-product-name": "Asapio BUS1006",
        "x-ep-displayname": "BUS1006",
        "x-ep-state-id": "2"
    },
    "x-parser-spec-parsed": true
}

There are multiple options to customise the AsyncAPI format - see eventApis resource

Create an Application Registration

Once a developer is interested in requesting access to Event API Products (EAP) we first need to register an application. Then we can add Access Requests for each EAP the developer wishes to use:

  1. Set {registrationId}: Each application registration requires a unique id.
    You can assign this id as required so you can easily find and retrieve the Application Registration.
  2. Set the source: Pass in an identifier or name for the instance of your system so your application registration can be attributed to its source.
  3. Set the owner (sourceOwner): If your system has an ownership model for application registration you can set a user or group name, user id or similar.

The successful response includes all the information you supplied. It also includes an initial set of credentials for the application that is stored securely in Solace Event Portal. You can manage credentials available to an Application Registration using the applicationRegistration/{registrationId}/credentials resources.

Other elements such as the accessRequests array are initially empty.

curl --location 'https://apim-devportal-api.solace-labs.io/api/v2/apim/appRegistrations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<api-token>>' \
--data '{
  "registrationId": "myapp",
  "source": "myAPIM",
  "name": "My App",
  "sourceOwner": "A name"
}'
{
    "data": {
        "registrationId": "myapp",
        "source": "myAPIM",
        "name": "My App",
        "sourceOwner": "A name",
        "accessRequests": [],
        "apis": [],
        "filters": [],
        "credentials": [
            {
                "secret": {
                    "consumerKey": "YMLNU3SzUCiLRFZwWD3YWHfT6FS1eD3P",
                    "consumerSecret": "PpnsGsoTW8fqKaHP"
                },
                "issuedAt": 1696406691267,
                "expiresAt": -1
            }
        ],
        "gatewayMessagingServices": [],
        "webhooks": [],
        "brokerType": "solace"
    },
    "meta": {}
}

Add an Access Request

📘

You need an eventApiProductId and planId that you obtained previously and also the registrationId you used in the previous step

Finally let's create an Access Request once a developer has decided which Event API Product (EAP) they want to use:

  1. Set the {registrationId} in the URL
  2. Set accessRequestId in the payload: each access request requires a unique id within the Application Registration.You can assign this id as required so you can easily find and retrieve the Access Request
  3. Set eventApiProductId and {planId}
curl --location 'https://apim-devportal-api.solace-labs.io/api/v2/apim/appRegistrations/{registrationId}/accessRequests' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<api-token>>' \
--data '{
  "accessRequestId": "{accessRequestId}",
  "eventApiProductId": "{eventApiProductId}",
  "planId": "{planId}"
}'
{
    "data": {
        "accessRequestId": "my-access-request",
        "eventApiProductId": "kils37cwlkz",
        "planId": "8a0g3o0prdf",
        "registrationId": "myapp",
        "filters": [],
        "eventApiProductVersion": "1.7.0",
        "state": "APPROVED",
        "eventApiResourceInformation": [
            {
                "accessType": "exclusive",
                "maxMsgSpoolUsage": 1,
                "maxTtl": 1,
                "name": "myapp/kils37cwlkz/8a0g3o0prdf/BUS1006",
                "eventApiId": "29591g18w8q"
            }
        ],
        "permissions": {
            "publish": [
                {
                    "sap_demo/BUS1006/sap-bo-data/update/json/v1/asadev/emptyType/ERD100/{REFERENCE}": {
                        "permissions": [
                            "sap_demo/BUS1006/sap-bo-data/update/json/v1/asadev/emptyType/ERD100/>"
                        ],
                        "isChannel": true
                    }
                }
            ],
            "subscribe": []
        },
        "messagingServiceConnections": [
            {
                "name": "APIM-GW-DEV",
                "protocol": "mqttws",
                "protocolVersion": "3.1.1",
                "url": "ws://mr-connection-6mdexb3glmb.messaging.solace.cloud:8000",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "secure-mqttws",
                "protocolVersion": "3.1.1",
                "url": "wss://mr-connection-6mdexb3glmb.messaging.solace.cloud:8443",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "https",
                "protocolVersion": "1.1.0",
                "url": "https://mr-connection-6mdexb3glmb.messaging.solace.cloud:9443",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "amqps",
                "protocolVersion": "1.0.0",
                "url": "amqps://mr-connection-6mdexb3glmb.messaging.solace.cloud:5671",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "smfs",
                "protocolVersion": "1.0.0",
                "url": "tcps://mr-connection-6mdexb3glmb.messaging.solace.cloud:55443",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "amqp",
                "protocolVersion": "1.0.0",
                "url": "amqp://mr-connection-6mdexb3glmb.messaging.solace.cloud:5672",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "smf",
                "protocolVersion": "1.0.0",
                "url": "tcp://mr-connection-6mdexb3glmb.messaging.solace.cloud:55555",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "smfc",
                "protocolVersion": "1.0.0",
                "url": "tcps://mr-connection-6mdexb3glmb.messaging.solace.cloud:55003",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "http",
                "protocolVersion": "1.1.0",
                "url": "http://mr-connection-6mdexb3glmb.messaging.solace.cloud:9000",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "mqtt",
                "protocolVersion": "3.1.1",
                "url": "tcp://mr-connection-6mdexb3glmb.messaging.solace.cloud:1883",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "secure-mqtt",
                "protocolVersion": "3.1.1",
                "url": "ssl://mr-connection-6mdexb3glmb.messaging.solace.cloud:8883",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            }
        ]
    },
    "meta": {}
}

New Access Requests usually are either in APPROVED or AWAITING_APPROVAL state. Once the event gateways (brokers) are configured the state changes to LIVE.

We can check the state of the access request we added:

  1. Set registrationId in the URL
  2. Set accessRequestId in the URL

Examine the state of the access request in the response.

curl --location --request GET 'https://apim-devportal-api.solace-labs.io/api/v2/apim/appRegistrations/{registrationId}/accessRequests/{accessRequestId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<api-token>>'

{
    "data": {
        "accessRequestId": "my-access-request",
        "eventApiProductId": "kils37cwlkz",
        "planId": "8a0g3o0prdf",
        "registrationId": "myapp",
        "filters": [],
        "eventApiProductVersion": "1.7.0",
        "state": "LIVE",
        "eventApiResourceInformation": [
            {
                "accessType": "exclusive",
                "maxMsgSpoolUsage": 1,
                "maxTtl": 1,
                "name": "myapp/kils37cwlkz/8a0g3o0prdf/BUS1006",
                "eventApiId": "29591g18w8q"
            }
        ],
        "permissions": {
            "publish": [
                {
                    "sap_demo/BUS1006/sap-bo-data/update/json/v1/asadev/emptyType/ERD100/{REFERENCE}": {
                        "permissions": [
                            "sap_demo/BUS1006/sap-bo-data/update/json/v1/asadev/emptyType/ERD100/>"
                        ],
                        "isChannel": true
                    }
                }
            ],
            "subscribe": []
        },
        "messagingServiceConnections": [
            {
                "name": "APIM-GW-DEV",
                "protocol": "mqttws",
                "protocolVersion": "3.1.1",
                "url": "ws://mr-connection-6mdexb3glmb.messaging.solace.cloud:8000",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "secure-mqttws",
                "protocolVersion": "3.1.1",
                "url": "wss://mr-connection-6mdexb3glmb.messaging.solace.cloud:8443",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "https",
                "protocolVersion": "1.1.0",
                "url": "https://mr-connection-6mdexb3glmb.messaging.solace.cloud:9443",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "amqps",
                "protocolVersion": "1.0.0",
                "url": "amqps://mr-connection-6mdexb3glmb.messaging.solace.cloud:5671",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "smfs",
                "protocolVersion": "1.0.0",
                "url": "tcps://mr-connection-6mdexb3glmb.messaging.solace.cloud:55443",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "amqp",
                "protocolVersion": "1.0.0",
                "url": "amqp://mr-connection-6mdexb3glmb.messaging.solace.cloud:5672",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "smf",
                "protocolVersion": "1.0.0",
                "url": "tcp://mr-connection-6mdexb3glmb.messaging.solace.cloud:55555",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "smfc",
                "protocolVersion": "1.0.0",
                "url": "tcps://mr-connection-6mdexb3glmb.messaging.solace.cloud:55003",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "http",
                "protocolVersion": "1.1.0",
                "url": "http://mr-connection-6mdexb3glmb.messaging.solace.cloud:9000",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "mqtt",
                "protocolVersion": "3.1.1",
                "url": "tcp://mr-connection-6mdexb3glmb.messaging.solace.cloud:1883",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            },
            {
                "name": "APIM-GW-DEV",
                "protocol": "secure-mqtt",
                "protocolVersion": "3.1.1",
                "url": "ssl://mr-connection-6mdexb3glmb.messaging.solace.cloud:8883",
                "bindings": {
                    "msgVpn": "apim-gw-dev"
                }
            }
        ]
    },
    "meta": {}
}