Event Portal API Code Samples

You can use the Event Portal APIs to retrieve, search, and create different Event Portal objects. On this page, we walk you through some of the common tasks you can perform using the API. The goal of these API code samples is to help you learn the basics to get started with Event Portal REST API quickly. Once you understand the basics, you can refer to the Event Portal Open API Spec to review other REST API endpoints.

REST API for Event API Product (EAP) is currently not available through the above mentioned URL. Information about EAP''s REST API is available in Event Portal API Code Samples

Prerequisites

To get started, you will need:

  • A Event Portal REST API account. If you don't have an account yet, go ahead and create a free trial account.
  • A REST client of your choice. In this tutorial, we will use Postman (6.1.3 or greater). Postman is a good choice if you want a visual REST API development tool.
  • An API token with Event Portal permissions. See the instructions below to Create an API Token.

Create an API Token

You need an API token to authenticate and authorize REST requests. When creating the token, you must also set the necessary Event Portal permissions.

  1. Log into your PubSub+ Cloud account.

    If you're already logged in to the PubSub+ Cloud and belong to multiple accounts (Workspaces), ensure that you select the account that you want to create an API token for. To do this, click User & AccountUser icon in the PubSub+ Cloud Console from the navigation bar, and in the submenu below the Notifications Settings, select the account you want to create an API token for.

  2. At the bottom of the left-hand menu, click the user icon, and then click Token Management.

  3. On the top-right corner, click the Create Token button.
  4. On the Create Token page, in the Token Name box, type a unique name for the API token.
  5. Navigate to Event Portal section and on the Select Permissions section, click the toggle Greyed out slider indicating off beside the permission you want to enable.

    The permissions you can set and see depend on your assigned account role. If you don't see some permissions (or see additional permissions) listed on the Create Tokenpage as shown in the illustration, you may not have the required permissions for your account. Contact your account administrator or Solace support if there is a problem with your permissions.

    The permissions shown below are useful for completing the tutorials and for development purposes only to fully utilize the REST API capabilities. API tokens that you use in production must assign only the minimum set of permissions (a subset of the above permissions) that are required for your client applications to function. For example, don't assign a permission such as Create User or Delete User if the application never needs to manage users. For more information, see Understanding API Token Permissions.

    The example shown below is useful for completing the tutorials or for development purposes only. The recommended practice is to create multiple API tokens with a subset of required permissions.

    Event Portal permissions:

Once the token is generated, you must authorize a REST request from your REST client to Event Portal.

Authorize REST requests from Postman to Event Portal

To authorize REST requests from Postman to PubSub+ Cloud, you must set the Postman apiToken to the token you just created. For Event API Products authorization, refer to Authorize REST requests from Postman to Event API Product.

  1. Download the Event Portal API collections and environment, and import them into Postman. Download
  2. Once both the files are imported, set the Environment to Event Portal API.

  3. Edit the Event Portal API environment by clicking the Environment quick look (eye icon)Edit.
  4. Paste the token in the Current Value field of the apiToken key.

  5. Click Update.

We now have a token, and Postman is set up to use it. Let's take a look at some of the common Event Portal tasks you can perform using Event Portal REST APIs.

Authorize REST requests from Postman to Event API Product

To authorize REST requests from Postman to Event API Product, include your API Products AsyncAPI Read security token as an HTTP header: Authorization: Bearer <API token goes here>.

For more information, refer to Retrieve an EAP's AsyncAPI Document (Partner Developers)

Retrieving Information of all Instances of an Object

You can call the REST endpoints to retrieve information of all instances of a specific object type. In the examples below, we will show you how to retrieve information of all instances for a specific object.

  1. In the Postman, navigate to CollectionsEvent Portal APIGet Objects folder.
  2. From the available options—Get Schemas, Get Events, Get Application, or Get Application Domain—select the request for which you want to retrieve the information. In this example, we select Get Schemas to retrieve information of all instances of a schema.

  3. Click Send. You will see the information of all instances of an object (Schemas in this example) in the bottom panel.

Retrieving Information of a Specific Instance of an Object

To fetch the details of a specific Event Portal object, you can pass in its ID to the relevant API or provide its Name as a query parameter.

Using the Object Name To Retrieve Information

  1. In the Postman, navigate to CollectionsEvent Portal APIGet Object By Name folder.
  2. From the available options — Get Schema, Get Event, Get Application, Get Application Domain, Get Tag — select an object for which you want retrieve the information. In this example, we select Get Schema.

  3. In the request URL, change the name to the name of the object you want.

  4. Click Send. You should see the details of the specified object in the bottom panel.

  5. In the information shown in the bottom panel, one of the fields is the ID of the specified object. In the example, the ID is saved as the current schemaId value of the environment. You can check by comparing the value in the bottom panel with that of the Event Portal API environment. To do so, click the Environment quick look (eye icon ), you will see the Event Portal API environment’s values.

    If you can cannot find the ID in the bottom panel, you most likely entered the name of the object incorrectly, or entered the name of a object that does not exist.

Using Object ID To Retrieve Information

  1. In the Postman, navigate to CollectionsEvent Portal APIGet Object By Id folder.
  2. From the available options—Get Schema, Get Event, Get Application, Get Application Domain, Get Tag — select an object for which you want retrieve the information. In this example, we will select Get Schema.

  3. In the request URL, change the ID to the ID of the desired object.

  4. Click Send. You will see the details of the specified object in the bottom panel.

Creating an Instance of an Object

In this example, we will walk you through the steps to create an instance of an object using the Event Portal API.

  1. In the Postman, navigate to CollectionsEvent Portal APICreate Objects folder.
  2. From the available options — Create Schema, Create Event, Create Application, Create Application Domain, or Create Tag —select the request you want to create. In this example, we select Create Event to create an event instance.

  3. In the request body, modify the fields to contain the information you want in your new instance. You can find more information about the modifiable fields in the Event Portal Open API Spec.

  4. Click Send. You will see the details of the created instance in the bottom panel. You can also verify that the instance was created by performing a REST call using the created instance’s Name or ID.

  5. If you are creating an application domain, you will notice the following:
    1. You will see the status of your request to be 202 Accepted, with no details of the created application domain in the bottom panel.

    2. You can confirm that the application domain was created by performing a REST call using the created application domain’s name or ID. To find the newly created application domain’s ID, navigate to the HeadersKeyLocation in the bottom panel. Take a look at the value give to the Key Location; the combination of letters and numbers after the final / is your newly created application domain’s ID.

Deleting an Instance of an Object

In this example, we will walk you through the steps to delete an instance of an object using the Event Portal API.

  1. In the Postman, navigate to CollectionsEvent Portal APIDelete Objects folder.
  2. From the available options — Delete Schema, Delete Event, Delete Application, Delete Application Domain, or Delete Tag — select the request you want to delete. In this example, we select Delete Schema to delete a schema instance.

  3. In the request URL, the ID of the instance of an object you are deleting is required. If you already have the ID, you can add it to the request URL. For example, you can replace the {{schemaId}} with the schema’s ID. Alternatively, you can find the ID of the desired object by performing the following REST call, and the ID will be automatically set as the Event Portal API's environment variable.

  4. You should see the Status of your request be 204 No Content, with no details of the deleted schema in the bottom panel. To confirm that the schema was deleted, performing a REST call to get all schemas; the schema that you wanted to delete will no longer be listed.

Updating an Instance of an Object

In this example, we will show you how to update an instance of an object using the Event Portal API

  1. In the Postman, navigate to CollectionsEvent Portal APIUpdate Objects folder.
  2. From the available options— Update Schema, Update Event, Update Application, Update Application Domain, or Update Tag —select the request you want to update. In this example, we update a schema instance by selecting Update Schema.

  3. In the request URL, the ID of the instance of an object you are deleting is required. If you already have the ID, you can add it to the request URL. For example, you can replace the {{schemaId}} with the schema’s ID. Alternatively, you can find the ID of the desired object by performing the following REST call, and the ID will be automatically set as the Event Portal API's environment variable.

  4. In the request body, only include the fields that you want to be updated in your schema.

  5. Click Send. You should see the details of the updated schema in the bottom panel.

Specifying Events that an Application is Publishing / Subscribing to

In this tutorial, we walk you through the steps to specify events to which an application is publishing or subscribing.

Events Published

  1. In the Postman, navigate to CollectionsEvent Portal APIManage Application Events folder.
  2. Select the request Set Produced Events.

  3. In the request URL, you will need to add the ID of the application you will be publishing to. If you already have the ID of the application, you can replace the {{appId}} with the application’s ID. Otherwise, you can find the ID of the desired application by performing the following REST call and it will be automatically set as Event Portal API {{appId}} environment variable.

  4. In the request body, modify the list of producedEventIds to contain the event IDs you want your application to publish to. You can find the ID of a desired event by performing the following REST call.

  5. Click Send. You should see the IDs of the producedEventIds in the bottom panel. You can confirm that the application is publishing to the specified IDs by performing a REST call using the application’s Name or ID.

Events Subscribed

  1. In the Postman, navigate to CollectionsEvent Portal APIManage Application Events folder.
  2. Select the request Set Consumed Events.

  3. In the request URL, the ID of the application you will be subscribing to is required. If you already have the id of the application, you can replace the {{appId}} with the application’s ID. Otherwise, you can find the ID of the desired application by performing the following REST call and it will automatically be set as the Event Portal API {{appId}} environment variable.

  4. In the request body, modify the list of consumedEventIds to contain the event IDs you want your application to subscribe to. You can find the ID of a desired event by performing the following REST call.

  5. Click Send. You should see the IDs of the consumedEventIds in the bottom panel. You can also confirm that the application is subscribing to the specified ids by performing a REST call using the application’s Name or ID.

Configuring an Event's Payload Schema

  1. In the Postman, navigate to CollectionsEvent Portal APIUpdate Objects.
  2. Select the request Update Schema of Event.

  3. In the request URL, the ID of the event you will be linking the schema to is required. If you already have the ID of the event, you can replace the {{eventId}} with the event’s ID. Alternatively, you can find the ID of the desired event by performing the following REST call and it will be automatically set as the Event Portal API {{eventId}} environment variable.

  4. In the request body, modify the schemaId to contain the schema ID you want your event to be linked to. You can find the ID of the desired schema by performing the following REST call.

  5. Click Send. You should see the ID of the schemaId in the bottom panel. You can also confirm that the event contains the specified schema by performing a REST call using the event’s name or ID.

Adding an Owner to an Object

For all Event Portal objects, the owner cannot be assigned when creating the object. Instead, the owner can only be modified after the object has been created. The following example walks you through the steps to add an owner to an object:

  1. In the Postman, navigate to CollectionsEvent Portal APIAdd Owner To Object.
  2. From the available options—Set Schema Owner, Set Event Owner, Set Application Owner, Set Application Domain Owner—select the desired request. In this example, we will select the request Set Schema Owner.

  3. To add an owner to an object, you must add the ID of the object in the request URL. If you already have the ID, you can add it to the request URL. For example, if you are adding an owner to a schema, you can replace the {{schemaId}} in the request URL with the ID of the schema. Alternatively, you can find the ID of the desired object by performing the following REST call, and the ID will be automatically set as the Event Portal API's environment variable.

  4. In the request body, modify the list of ownerIds to the owner IDs you want your object to have as its owners.

  5. Click Send. You will see list of owner IDs for the requested object in the bottom panel.

Adding a Tag to an Object

You can add a tag to a schema, event, or an application. In the following example, we will show you how to add a tag to an object using the Event Portal REST API

  1. In the Postman, navigate to CollectionsEvent Portal APIAdd Tag To Object
  2. From the available options—Set Schema Tag, Set Event Tag, and Set Application Tag—select the desired request. In this example, we will select the Set Application Tag.

  3. To add a tag to an object, you must add the ID of the object you will be adding the tags to in the request URL. If you already have the ID of the object, you can add it to the request URL. For example, if you are adding an tag to an application, you can replace the {{appId}} in the request URL with the ID of the application. Alternatively, you can find the ID of the desired object by performing the following REST call, and the ID will be automatically set as the Event Portal API's environment variable.

  4. In the request body, modify the list of tagIds to contain the tag IDs you want your object to have.

  5. Click Send. You should see the IDs of the tagIds in the bottom panel.

Retrieve an EAP's AsyncAPI Document (Partner Developers)

To retrieve the AsyncAPI document, your will need to generate the API Products AsyncAPI Read security token and share it with your partner developers requiring access to the EAP's AsyncAPI document. Your partner developers will need the security token to authorize REST requests from their REST Client to Event Portal. You can generate the token in the PubSub+ Cloud console.

The EAP must be marked as Released in the console for it to be accessible through these public REST APIs.

After an EAP is released, your partner developers can retrieve it's AsyncAPI document using a GET call to one of the following endpoints:

  • /api/v0/eventPortal/apiProducts/{productId}/asyncApi.json
  • /api/v0/eventPortal/apiProducts/{productId}/asyncApi.yaml

In the example below, a POST call to /api/v0/eventPortal/apiProducts/{productId}/asyncApi.yaml retrieves the EAP's AsyncAPI document in YAML format. A successful response returns 200 OK with the AsycnAPI details in the payload.

A similar call can be made to retrieve the EAP’s AsyncAPI in JSON format using a POST call to /api/v0/eventPortal/apiProducts/{productId}/asyncApi.json.

The following Postman screenshot illustrates an AsyncAPI document retrieved in YAML format.

Note that if a Kafka Key is a primitive type, the name of primitive type will be displayed in the payload; otherwise, it will be a reference ($ref) to the schema in schema section.