Understanding and Testing the PubSub+ Event Portal REST API
Tags: fordevelopers
Published: 2020-11-19 14:06:32

---
title: Understanding and Testing the PubSub+ Event Portal REST API
published: true
date: 2020-10-27 11:30:54 UTC
tags: ForDevelopers
canonical_url: https://solace.com/blog/testing-the-pubsub-event-portal-rest-api/
---

 ![](https://solace.com/wp-content/uploads/2020/04/blog-featured-image-pubsubplus-event-portal.jpg) 

Whether it is CI/CD pipelines, event flow documentation systems, or using [PubSub+ Event Portal](https://solace.com/products/portal/) as the unique event design and documentation tool for all your events in your enterprise, I’m sure you would appreciate an API to gather all the information. This is why PubSub+ Event Portal provides a REST API, which is compliant with the OpenAPI specification.

The goal of this tutorial is to explain how this API works. It will also guide you through the steps needed to REST-enable Section 4 of this [codelab](https://codelabs.solace.dev/codelabs/design-to-code-workshop/#3) (done using PubSub+ Event Portal GUI).

## Understanding PubSub+ Event Portal REST API

The PubSub+ Event Portal REST API provides the ability to interact with the PubSub+ Event Portal using RESTful patterns. For instance, it provides ways to browse artefacts, create, update, and delete events or applications. This is an easy way to integrate systems in a programmatic manner with the PubSub+ Event Portal Designer and Catalog.

The PubSub+ Event Portal REST API has an OpenAPI specification document available at [https://openapi.solace.cloud](https://openapi.solace.cloud).

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-1.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-1.png)

## **Prerequisites to access the REST API**

In order to perform REST API calls, you need an API token. Follow the steps to get that token:

1. Log in to your [PubSub+ Cloud](https://console.solace.cloud/) account
2. Click on your name and go to the [Token Management](https://console.solace.cloud/api-tokens) menu in the console  
[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-2.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-2.png)
3. Click **Create Token  
[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-3.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-3.png)**  
4. Give it a name and enable read & write permissions for PubSub+ Event Portal. You could choose to only enable read or write, depending on your needs, but in this tutorial we are going to use both read and write access.  
[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-4.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-4.png)
5. Click **Generate Token** and in the popup dialogue box click **Copy** to store a copy of the token.

## Testing the Event Portal REST API

In this section, you are going to REST-enable Section 4 of this [codelab](https://codelabs.solace.dev/codelabs/design-to-code-workshop/#3), which was done using the PubSub+ Event Portal GUI.

From [https://console.solace.cloud](https://console.solace.cloud), click the PubSub+ Event Portal **Designer** , either by clicking on the left menu or the right-hand side Event Portal Designer menu.

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-5-1024x573.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-5.png)

Enter the **Acme Rideshare** domain, which is created by default.

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-6.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-6.png)

As described in the [codelab](https://codelabs.solace.dev/codelabs/design-to-code-workshop/#3), we are going to follow these steps:

- Create an application
- Create an event
- Update the created application to publish this event

## **Creating the _RideDropoffProcessor_ Application**

According to the [Event Portal OpenAPI specification](https://openapi.solace.cloud/), to create an application using the _POST_ verb for the _Applications_ resource, we first need a domain id.

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-7.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-7.png)

So, let’s get the Acme Rideshare domain id. For this, choose the tool you are comfortable with to perform HTTP requests. This tutorial uses Postman, but curl would also be fine.  To get the domain id, use the GET verb on the _applicationDomains_ resource with the _name_ parameter.

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-8.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-8.png)

You should then use the following parameters:

- Url: [https://solace.cloud/api/v1/eventPortal/applicationDomains?name=Acme%20Rideshare](https://solace.cloud/api/v1/eventPortal/applicationDomains?name=Acme%20Rideshare)
- HTTP verb: **GET**
- HTTP Authorization header: add the previously generated token as **Bearer Token**

If you are using Postman, you should get the following response:

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-9.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-9.png)

In the response, locate the **id** element. This is your domain id. In this example, the id is _pjn25g5eqlz_.

You can now go ahead and create your application by using the following settings:

- Url: [https://solace.cloud/api/v1/eventPortal/applications](https://solace.cloud/api/v1/eventPortal/applications)
- HTTP verb: **POST**
- HTTP Content-type: **application/json**
- HTTP Authorization header: add the previously generated token as **Bearer Token**
- Payload: make sure you use your own domain id

```

{
"name": "RideDropoffProcessor",
"description": "Application created by Solace Event Portal REST API",
"applicationDomainId": "pjn25g5eqlz",
"revisionComment": "application creation",
"applicationClass": "unspecified"
}

```

If you are using Postman to post this request, you should get the following response:

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-10.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-10.png)

At this stage, write down your application id (you will need it at a later step). In this example, the application id is q956yss2nqj.

Switch back to Designer, in the **Applications** tab, you now see the newly created application. In my case, it is at the end of the list:

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-11.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-11.png)

## **Creating the Event _RideAverageUpdate_**

Start by understanding the [OpenAPI specification](https://openapi.solace.cloud/#/Events/add) to create an event.

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-12.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-12.png)

The mandatory elements are name and topic, but since we are following Section 4 of the [codelab](https://codelabs.solace.dev/codelabs/design-to-code-workshop/#3), we also need to link this event to a schema id. This means that the schema has to be created first, and then we’ll get its id.

So, let’s first create the schema. Same as before, we start by having a look at the OpenAPI specification for creating a schema.

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-13.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-13.png)

In our context, this means:

- Url: [https://solace.cloud/api/v1/eventPortal/schemas](https://solace.cloud/api/v1/eventPortal/schemas)
- HTTP verb: **POST**
- HTTP Content-type: **application/json**
- HTTP Authorization header: add the previously generated token as **Bearer Token**
- Payload: (make sure you use your own domain id)

```

{
"name": "RideAveragePayload",
"shared": false,
"description": "Event Payload which contains average meter readings, average passenger counts, and the number of rides in a given window duration",
"revisionComment": "Schema creation",
"contentType": "JSON",
"content": "{ \"$schema\": \"http://json-schema.org/draft-07/schema\",\"$id\": \"http://example.com/example.json\",\"type\": \"object\",\"title\": \"The root schema\",\"description\": \"The root schema comprises the entire JSON document.\",\"default\": {},\"examples\": [{\"timestamp\": \"2020-06-04T20:09:59.99832-04:00\",\"avg_meter_reading\": 21.615217,\"avg_passenger_count\": 1.5,\"window_duration_sec\": 300,\"window_ride_count\": 5}],\"required\": [\"timestamp\",\"avg_meter_reading\",\"avg_passenger_count\",\"window_duration_sec\",\"window_ride_count\"],\"additionalProperties\": true,\"properties\": {\"timestamp\": {\"$id\": \"#/properties/timestamp\",\"type\": \"string\",\"title\": \"The timestamp schema\",\"description\": \"An explanation about the purpose of this instance.\",\"default\": \"\",\"examples\": [\"2020-06-04T20:09:59.99832-04:00\"]},\"avg_meter_reading\": {\"$id\": \"#/properties/avg_meter_reading\",\"type\": \"number\",\"title\": \"The avg_meter_reading schema\",\"description\": \"An explanation about the purpose of this instance.\",\"default\": 0.0,\"examples\": [21.615217]},\"avg_passenger_count\": {\"$id\": \"#/properties/avg_passenger_count\",\"type\": \"number\",\"title\": \"The avg_passenger_count schema\",\"description\": \"An explanation about the purpose of this instance.\",\"default\": 0.0,\"examples\": [1.5]},\"window_duration_sec\": {\"$id\": \"#/properties/window_duration_sec\",\"type\": \"integer\",\"title\": \"The window_duration_sec schema\",\"description\": \"An explanation about the purpose of this instance.\",\"default\": 0,\"examples\": [300]},\"window_ride_count\": {\"$id\": \"#/properties/window_ride_count\",\"type\": \"integer\",\"title\": \"The window_ride_count schema\",\"description\": \"An explanation about the purpose of this instance.\",\"default\": 0,\"examples\": [5]}}}",
"applicationDomainId": "pjn25g5eqlz"
}

```

If you are using Postman to post this request, you should get the following response:

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-14.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-14.png)

Copy and paste the id from the response. In my case, the schema id is _q956yss2o5t_. If you switch back to Designer and go to the **Schemas** tab, you’ll see the newly created schema.

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-15.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-15.png)

You can now create the _RideAverageUpdate_ event using the following settings:

- Url: [https://solace.cloud/api/v1/eventPortal/events](https://solace.cloud/api/v1/eventPortal/events)
- HTTP verb: **POST**
- HTTP Content-type: **application/json**
- HTTP Authorization header: add the previously generated token as **Bearer Token**
- Payload: make sure you add your own schema id and domain id

```

{
"name": "RideAverageUpdate",
"shared": false,
"topicName": "taxi/nyc/v1/stats/dropoff/avg",
"description": "This event contains the average cost of rides over a specified duration",
"schemaId": "q956yss2o5t",
"applicationDomainId": "pjn25g5eqlz",
"revisionComment": "Event creation",
"brokerType": "solace",
"type": "event"
}

```

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-16.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-16.png)

At this stage, write down your event id (you will need it at a later step). In this example, the event id is _q956yss2oiv_.

Finally, switch back to Designer to visualize the _RideAverageUpdate_ event that was created.

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-17.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-17.png)

You can also check the details of the event and you’ll find attached the _RideAveragePayload_ schema:

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-18.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-18.png)

## **Update the created application**

Finally, in order to complete Step 4 of the [codelab](https://codelabs.solace.dev/codelabs/design-to-code-workshop/#3), you need to update the application _RideDropoffProcessor_ to publish the _RideAverageUpdate_ event. As always, start by understanding how to update an application by reading the OpenAPI specification, in the Applications resource, PATCH verb.

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-19.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-19.png)

We need the application id (which will be added to the URI) and the fields that need to be updated. In this example, they are the _revisioncomment_ element and the _producedEventIds_ element.

You can now update the application with the following settings:

- Url: [https://solace.cloud/api/v1/eventPortal/applications/q956yss2nqj](https://solace.cloud/api/v1/eventPortal/applications/q956yss2nqj) (make sure you use your own application id)
- HTTP verb: **PATCH**
- HTTP Content-type: **application/json**
- HTTP Authorization header: add the previously generated token as **Bearer Token**
- Payload: make sure you add your own event id

```

{
"revisionComment": "Changed published event",
"producedEventIds": [
"q956yss2oiv"
]
}

```

If you are using Postman, you should get a response similar to the one below:

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-20.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-20.png)

Finally, switch back to Designer to see the event _RideAverageUpdate_ published by the _RideDropoffProcessor_ application:

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-21.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-21.png)

You can also check the application revision history by clicking the three dots button at the end of the application line:

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-22-1024x228.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-22.png)

The revision history displays the update performed:

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-23.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-23.png)

## **Optional last step: AsyncAPI generation**

Now that you have created the application _RideDropOffProcessor_, you can now begin implementing it. But where to start? And how? One easy way is to start with AsyncAPI, and then use an AsyncAPI code generator.

AsyncAPI has emerged as the industry standard for defining asynchronous, event-driven APIs. You can think of it as OpenAPI for the asynchronous world. It is an open source initiative that provides both a specification to describe and document your asynchronous applications in a machine-readable format, and tooling (such as code generators) to make life easier for developers tasked with implementing them.

The Event Portal REST API enables you to automate the creation of an AsyncAPI document. That will define the application you want to develop. This step describes how to generate this document using the REST API.

So, let’s have a look at the [AsyncAPI resource](https://openapi.solace.cloud/#/AsyncAPI) in the PubSub+ Event Portal REST API.

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-24.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-24.png)

All you need is the application id, which you got previously. It  will be passed in the URI and the AsyncAPI version to be generated which will be part of the payload to be sent. You can then generate your AsyncAPI document for the application by using the following settings:

- Url: [https://solace.cloud/api/v1/eventPortal/applications/q956yss2nqj/generateAsyncApiRequest](https://solace.cloud/api/v1/eventPortal/applications/q956yss2nqj/generateAsyncApiRequest) (make sure you use your own application id)
- HTTP verb: **POST**
- HTTP Content-type: **application/json**
- HTTP Authorization header: add the previously generated token as **Bearer Token**
- Payload:

```

{
"asyncApiVersion": "2.0.0"
}

```

If you are using Postman, you should get a similar response:

[![](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-25.png)](https://solace.com/wp-content/uploads/2020/10/event-portal-rest-api-25.png)

The response contains the AsyncAPI document, describing the _RideDropOffProcessor_ application. Looking for a next step to generate the application code? Refer to Steps [5](https://codelabs.solace.dev/codelabs/design-to-code-workshop/#4) and [6](https://codelabs.solace.dev/codelabs/design-to-code-workshop/#5) of the [codelab](https://codelabs.solace.dev/codelabs/design-to-code-workshop/#0).

## **Conclusion**

PubSub+ Event Portal is an excellent tool to design and visualize your event-driven architecture, discover what events exist, and collaborate with your team. Using its REST API, you can automate the creation and modification of all your event-driven artefacts. Using AsyncAPI, your developers can generate the application code skeleton by leveraging the AsyncAPI code generator.  If you have any questions about PubSub+ Event Portal and its REST API, post them to the [**Solace Developer Community**](https://solace.community/).

The post [Understanding and Testing the PubSub+ Event Portal REST API](https://solace.com/blog/testing-the-pubsub-event-portal-rest-api/) appeared first on [Solace](https://solace.com).