You may have partner developers who want to use your event data to build new applications, or your partner organizations may need access to certain events to explore new business opportunities. As an event API provider, you can bundle your events into an Event API Product (EAP), and release them to external developers for consumption, enabling them to build event-driven applications that can subscribe to and/or publish the specified events. An Event API Product can be composed of events from either PubSub+ Event Broker or Kafka.
You can use the Event API Products in the following ways:
- Download its associated AsyncAPI document from the Event Portal UI and share the file with external developers.
- Fetch its associated AsyncAPI document through REST GET API call enabling its integration into systems such as third-party API Portals.
- Provide its associated AsyncAPI document as a publicly hosted website to external developers, allowing them to browse and download the AsyncAPI document.
The events bundled in an EAP can be added from one or more application domains, so you can mix and match events, as shown in the figure below.
The following fictional airline example shows how related events can be bundled into different EAPs, enabling both internal and external consumers to access the EAP's underlying events for their business needs.
An Event API Product bundles together the following information:
- events you want to expose
- associated schema information
- information about the event operation (publish and/or subscribe)
In the next few topics, we will dive into the detailed features and functionalities of Event API Products.
Before your begin
- Ensure that you have the correct user role and permission in Event Portal. At the minimum, you will need the Event Portal Manager permission. For more information, refer to Managing Users, Groups, Roles, and Permissions.
- Only events marked as shared in Designer can be part of an Event API Product. To learn how to mark an event as shared, refer to Creating an Event.
- For EAP's REST API documentation, refer to Event Portal v1 REST API.
Creating an Event API Product
You can create an Event API Product (EAP) containing a subset of events from one or more application domains. You can add events while creating an EAP or edit an existing EAP to add new events. Events must be marked as shared in Designer to be part of an Event API Product. The LEM filters the list of available shared events that can be added to an EAP. When adding an event, you can set the event operation to subscribe, publish, or both. The subscribe option is enabled by default.
Furthermore, you can include the same event across multiple EAPs, and the event can have different publish or subscribe operations across the EAPs. After an EAP is created, its AsyncAPI document will be immediately available for download from the console. However, to provide access externally, you must first release the EAP. A maximum of twenty EAPs can be created per account.
In the example below, we will create an EAP and add events to it.
-
Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your
- Select Event API Products on the welcome screen or the API Products icon on the left navigation bar.
- If you are haven't previously created an EAP, the Event API Products page will be empty. Click Create.
- On the Create Event API Products page, perform the following tasks:
- Give a Name to the EAP. The name must be unique.
- Select a Logical Event Mesh. Only shared events from the selected LEM can be added to an EAP. Note that once an EAP is created, you cannot change the LEM.
- Write a Summary.
- Provide a detailed Technical Description.
- Optionally, add the server settings information:
- Server URL. A URL that applications can use to connect to a specific server and start sending and/or receiving data. For more information refer to Server Objects section in the AsyncAPI documentation.
- Server Protocol. A mechanism (wireline protocol OR API) by which messages are exchanged between applications. For more information refer to Protocol section in the AsyncAPI documentation.
- At this stage, your EAP does not have any events. Select the Events tab to add one or more shared events.
- Click the Add Events button.
- On the dialog that appears, select the checkbox beside the event you want to use. You can select multiple events. Once you have selected the events you want to add to the Event API Product, click Apply.
Perform a search to find the events you want to use.
- (Optional) After adding the events, configure the event operation to publish, subscribe, or both. The subscribe option is selected by default. Configuring the pub/sub operation on an event should be done from the client application perspective. For example, an event selected as “subscribed,” implies that a client application using the EAP’s AsyncAPI can choose to “subscribe” to receive this event.
- Click Save.
Your newly created EAP will be available on the Event API Products page, and it will have a Not released status. There are a few useful visualizations to help you identify an EAP's release status.
-
or 
- The EAP is publicly available through the REST API -
or 
- Publicly available through a hosted website -
- The EAP is not yet released.
After adding events to the EAP, you can do the following:
- Download the EAP's AsyncAPI document and send it to your partner developer. This is option is available in case you want to provide access to the EAP to your partner developers without exposing it publicly.
- Release the EAP and provide external access through REST API.
- Host a released EAP as a public website.
- Update the Event API Product.
- Update or Delete the EAP.
Downloading an EAP's AsyncAPI Document
In some situations, you may not want to release an Event API Product (EAP) externally. For example, some partner developers may work in a highly secure environment without internet access. In that case, you can download the Event API Product's Async API document from the console and share it with external partner developers so that they can host it on their own private servers.
To download an EAP's AsyncAPI document, do the following.
-
Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your
- Select Event API Products on the welcome screen or the API Products icon on the left navigation bar.
- On the Event API Products page, select an EAP.
- On the EAP page, click Download AsyncAPI.
- In the dialog that appears, select JSON or YAML.
- Click Download Async API.
Releasing an Event API Product
To provide external access to an Event API Product (EAP), you must first release it. After an EAP is released, external partners and developers can immediately access its AsyncAPI document using the public REST API. This allows external partners and developers to integrate the REST API into third-party API Portals to advertise the availability of the EAP. Optionally, you can make the EAP available as a hosted website so that your partner developers can view the EAP from their web browser and download the AsyncAPI document.
To release an EAP and optionally host its website, perform the following steps:
-
Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your
- Select Event API Products on the welcome screen or the API Products icon on the left navigation bar.
- On the Event API Products page, select an EAP.
- On the EAP page, click the Release button on the top right.
- On the dialog that appears, do the following:
- (Optional) Select the checkbox beside Host Website to host the EAP on a public web page. You can host an Event API Product website while releasing it or after. For additional information about hosting an EAP website, refer to Hosting an Event API Product Website.
- Click Release. After the EAP is released, the REST API icon will be visible on the EAP page. If you selected the Host Website option, the website icon will also display.
- You can now share the REST API URL or the website URL (if enabled) with your partner developers. On the EAP page, peform the following steps to share the REST API URL or the Website URL.
- REST API—select JSON or YAML format, and click Copy URL to share.
- Website—copy the URL to share or click the URL to open it in a new tab
Your partner developers can now retrieve the EAP’s AsyncAPI document through REST API or the hosted website, and integrate it into a third-party API Portal.
For information on how your partner developers can retrieve the AsyncAPI document using the public REST API, see Event Portal API Code Samples.
For information on using the EAP's hosted website, see Hosting an Event API Product Website.
Hosting an Event API Product Website
After releasing an Event API Product (EAP), you can make it available as a hosted website so that your partner developers can view the EAP from their web browser and download the AsyncAPI document. In the case of multiple EAP's, each published EAP is hosted on its own website. There are two ways you can enable the hosting of an Event API Product website:
- When releasing an EAP, you can optionally choose to host it as a website. To learn more, refer to Releasing an Event API Product
- Host an Event API Product website after it is released.
To host an Event API Product website after it has been released, perform the following steps:
-
Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your
- Select Event API Products on the welcome screen or the API Products icon on the left navigation bar.
- On the Event API Products page, select an EAP that has been released. A released EAP will have a green REST API icon () displayed on the card.
- On the EAP page, click Host Website located on the right pane.
- On the dialog that appears, click Host. Once an EAP is hosted as a public website, the following icons will be displayed on the EAP page: website () and REST API ().
- You can now obtain the EAP's public URL from the console and share it with your partner developers. To view the EAP's hosted website, click the URL to open it on a new tab.
Your partner developers—or, anyone with the URL—can browse the website to view the EAP’s AsyncAPI as a web document and download it in JSON or YAML format.
Unhosting an Event API Product Website
When you unhost an Event API Product website, external developers will not be able to view its AsyncAPI document or download it. To unhost an Event API Product website, do the following:
-
Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your
- Select Event API Products on the welcome screen or the API Products icon on the left navigation bar.
- On the Event API Products page, select an EAP with a hosted website. An EAP with a hosted website is indicated by a green and icons.
- On the EAP page, click Unhost Website located on the right pane.
- On the dialog that appears, click Unhost. The Event API Product will be unavailable as a hosted website.
Unreleasing an Event API Product
You can Unrelease an Event API Product, which will pull it back from the current release state.
When an EAP is unreleased, external users will no longer be able to use the Rest API or hosted website.
To unrelease an EAP, perform the following steps:
-
Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your
- Select Event API Products on the welcome screen or the API Products icon on the left navigation bar.
- On the Event API Products page, select an EAP.
- On the EAP page, click the Actions (...) on the top right.
- Select Unrelease.
- On the dialog that appears, click Unrelease.
Updating an Event API Product
You can update the following information for an existing Event API Product:
- Update the general information (Name, Summary, Technical Description, and server settings)
- Add new events
- Remove events
- Update the operation of existing events
You must re-release the EAP to apply the updates. Furthermore, if an event is deleted or updated in Designer, the changes will immediately apply to the AsyncAPI document that's downloadable from the console. However, the released version of the AsyncAPI document is not impacted by changes made in the Designer until the EAP is re-released. Therefore, the EAP must be re-released to pull in the event updates made in Designer. For more information on releasing an EAP's AsyncAPI document, see Releasing an Event API Product
Updating General EAP Information
To update the Name, Summary, Technical Description, or server settings of an EAP, do the following:
-
Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your
- Select Event API Products on the welcome screen or the API Products icon on the left navigation bar.
- Locate the Event API Product you want to update
- Click Actions (...) on the card and select Edit.
- On the Edit Event API Products page, update the general information.
- Click Save.
Deleting an EAP
To permanently delete an Event API Product (EAP) you must unrelease it. You cannot delete a released EAP.
Once an EAP is deleted, it cannot be restored.
To delete an EAP, do the following:
-
Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your
- Select Event API Products on the welcome screen or the API Products icon on the left navigation bar.
- Locate the Event API Product you want to update
- Click Actions (...) on the card and select Delete.
- On the dialog that appears, select Delete.
Updating or Deleting Events from an EAP
After adding events to an Event API Product (EAP), you can update it's operation (publish/subscribe) or remove events from it. Note that after updating an EAP, the updates must be released to make it externally available.
To update an existing EAP, do the following:
-
Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your
- Select Event API Products on the welcome screen or the API Products icon on the left navigation bar.
- Locate the Event API Product you want to update, click Actions (...) on the card, and select Edit
- On the Edit API Products Page, select the Events tab.
- You can now update the operation of the event or remove the event from the EAP.
- To update an event operation, select or deselect the Subscribe or Publish checkbox.
- To remove an event, select the remove icon (X)
- Click Save.
Retrieving an EAP's AsyncAPI Document using REST
After an EAP is released, your partner developers can retrieve the EAP's AsyncAPI document using the Event Portal REST API. This allows your partner developers to integrate the EAP into a third-party API Portal.