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. To get an EAP's AsyncAPI document, see Retrieve an EAP's AsyncAPI Document .

Prerequisites

To get started, you will need:

  • A Event Portal v1 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. For more information, see Creating an API Token.

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 an API token with Event Portal permissions. For Event API Product 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.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

  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 Event Portal API Code Samples

Retrieving Information for 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 Collections → Event Portal API → Get 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.

    Screenshot showing the settings described in the surrounding steps.

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

    Screenshot showing the settings described in the surrounding steps.

Retrieving Information for 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 Collections → Event Portal API → Get 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.

    Screenshot showing the settings described in the surrounding steps.

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

    Screenshot showing the settings described in the surrounding steps.

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

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

    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 Collections → Event Portal API → Get 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.

    Screenshot showing the settings described in the surrounding steps.

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

    Screenshot showing the settings described in the surrounding steps.

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

    Screenshot showing the settings described in the surrounding steps.

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 Collections → Event Portal API → Create 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.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

  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.

      Screenshot showing the settings described in the surrounding steps.

    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 Headers → Key → Location 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.

      Screenshot showing the settings described in the surrounding steps.

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 Collections → Event Portal API → Delete 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.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

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 Collections → Event Portal API → Update 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.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

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

    Screenshot showing the settings described in the surrounding steps.

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

    Screenshot showing the settings described in the surrounding steps.

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 Collections → Event Portal API → Manage Application Events folder.
  2. Select the request Set Produced Events.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

Events Subscribed

  1. In the Postman, navigate to Collections → Event Portal API → Manage Application Events folder.
  2. Select the request Set Consumed Events.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

Configuring an Event's Payload Schema

  1. In the Postman, navigate to Collections → Event Portal API → Update Objects.
  2. Select the request Update Schema of Event.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

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 Collections → Event Portal API → Add 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.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

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

    Screenshot showing the settings described in the surrounding steps.

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

    Screenshot showing the settings described in the surrounding steps.

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 Collections → Event Portal API → Add 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.

    Screenshot showing the settings described in the surrounding steps.

  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.

    Screenshot showing the settings described in the surrounding steps.

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

    Screenshot showing the settings described in the surrounding steps.

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

    Screenshot showing the settings described in the surrounding steps.

Retrieve an EAP's AsyncAPI Document

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.

Screenshot showing the settings described in the surrounding steps.

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.