Event API Products

Event API Products allow you to expose important event assets to other development teams, external partners, and customers. You create Event API Products by bundling one or more Event APIs, with service plan details that specify message delivery options. You can add Event API Products to modeled event meshes to model the event flows for the Event API Product at runtime.

You can expose Event API Products to third-party API management systems and developer portals, similar to the way REST APIs are exposed. External developers can then browse and register to use your Event API Products, similar to how they would use REST-based API Products.

You can create Event API Products only for Solace event brokers.

This section includes the following tasks:

• Creating an Event API Product
• Updating an Event API Product
• Changing the State of an Event API Product Version
• Adding an Event API Product to an Environment
• Making an Event API Product Publicly Available
• Downloading an Async API Document with Event API Product Information
• Deleting an Event API Product

You can also create custom attributes for Event API Products. For more information, see Using Custom Attributes

Creating an Event API Product

You create Event API Products within application domains. When you create an Event API Product, you can specify several options:

• name
• broker type
• whether the Event API Product can be shared for use in other application domains
• custom attributes for the object and for object versions
• version display name, number, and state for each version
• approval type for requests to use the Event API Product. You can allow external developer requests to be approved automatically, or, if you have an approval process in your API management system or developer portal, you can require requests to receive approval.
• service plans that specify the message delivery options available when external developers use your Event API Product to publish or consume events
• included Event APIs
• filters on topic address variables to restrict the events that can be captured by the Event API Product. For example, if an event in an included event API has a topic address with a variable that specifies a location, you can limit the locations captured by the Event API Product.

To create an Event API Product, perform these steps:

1. 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 authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
2. On the navigation bar, select Designer.
3. On the Application Domains page, select the application domain that you want to add the Event API Product to.
4. Click Components to switch to the list view.

5. Select the Event API Products tab, then click Create Event API Product.

   

6. Enter a Name for the Event API Product.
7. If you want the Event API Product to be available in other application domains, select Allow Event API Product to be shared across application domains.
8. (Optional) Add values for any object custom attributes that have been set up in your organization.
9. In the Version field, specify a semantic version value for the Event API Product in the format major.minor.patch. The default is 0.1.0.
10. (Optional) Enter a Version Name for the initial version of the Event API Product.
11. (Optional) Enter a Description for the Event API Product. The Description field supports Markdown. Click toggle preview to preview the rendered text.
12. In the Approval Type list, select Automatic if you don't require approval, or External if requests to use the Event API Product need to be approved.

13. Specify one or more service plans for customers to consume the events in the Event API Product. Click Add Plan to set the details for an additional plan. You can set the following options for each plan:

    Option	Description
    Plan Name	A descriptive name for the plan. For example, if you have three plans, you may want to use Bronze, Silver, and Gold
    Messaging	Select whether the plan offers Direct or Guaranteed messaging. For more information about the messaging types, see Direct Messages and Guaranteed Messages. The remaining options are available only if you select Guaranteed.
    Access Type	For Guaranteed Messaging, select whether the messages are stored in an Exclusive or Non-Exclusive queue. For more information, see Creating a Queue.
    Queue Type	For Guaranteed Messaging, specify whether consumers have a Combined Queue for all Event APIs or a Single Queue for each Event API. If the Event API Product contains more than one event API, this option specifies whether each event API publishes events to a dedicated queue, or if all event APIs publish events to the same queue.
    Maximum TTL	Specify the maximum number of seconds that an event remains in the queue.
    Spool Size	Specify the size of the queue in MB.

14. Select one or more event APIs to include in the Event API Product:
    1. Click Manage Event APIs.
    2. In the Application Domain list, select the application domain for the event API that you want to include. By default, the list shows event APIs from the current application domain. If you select a different application domain, the list shows shared event APIs in the selected application domain. If you remove the filter, the list shows shared event APIs in all application domains that you have access to.
    3. Expand an event API to see the list of versions.
    4. Select a version of the event API.
    5. When you are finished selecting events, click Close .
15. (Optional) If any events in the included event APIs have topic addresses that include variables, add filters to limit the events that can be captured.
    1. Click Expand for the event API to display the list of events.

    2. Click Filter

       

    3. To filter enumeration variables, in the field for the variable, click Remove for the items you don't want the Event API Product to include.
    4. To filter unbounded variables, in the field for the variable, type the values that you want the Event API Product to capture.
       • Use commas to separate values.
       • Use * to capture all values.
       • Append * to the end of a text string to specify a wildcard match.
    5. When you are finished setting filters, click Close.
16. (Optional) Add values for any version custom attributes that have been set up in your organization.
17. Click Save Event API Product.

Updating an Event API Product

When you update an Event API Product, you can update an existing version or create a new version. Versions allow you to work on updates and test new versions while the stable version remains in production. Each version also has a lifecycle state. You can only edit versions that are in Draft state. For more information, see Object Versions and Lifecycle States.

The version number uses semantic versioning in the format major.minor.patch. When you update an Event API Product, you have three options:

• If the Event API Product version is in Draft state, you can update an existing version and retain the version number.
• If the Event API Product version is in Released, Deprecated, or Retired state, you can duplicate a version and increment the version number to create a new Draft version.
• If the Event API Product version is in Released, Deprecated, or Retired state, you can create a new version from scratch.

If you want to update a version that is not in Draft state it is best practice to create a new version rather than returning the version to Draft state.

When you include an event API in an Event API Product, you select the version of the event API that you want to include. If a new version of an event API is created, you can choose when to update the Event API Product to include the new version.

To update an Event API Product, perform these steps:

1. On the Application Domains page, click the application domain that contains the Event API Product you want to update.
2. Click Components to switch to the list view.
3. Select the Event API Products tab.
4. Click the name of the Event API Product.
5. Perform one of the following actions:
• In the Versions list, click More Actionsfor the version that you want to update and select Edit. Any changes you make update that version of the Event API Product. You can edit an Event API Product version only if it is in Draft state.
• In the Versions list, click More Actionsfor the version that you want to update and select Duplicate. All properties of the existing version are copied into a new version. By default, the new version number is incremented by 0.0.1. You can change the version number to any number not already in use.
• Above the Versions list, click Addto create a new version of the Event API Product without duplicating an existing version. By default, the new version number is the next unused major version. You can change the version number to any number not already in use.
6. Update the Event API ProductI version as necessary.
7. Click Save Version or Save & Close.

Changing the State of an Event API Product Version

When you create a new version of an Event API Product, the version is in Draft state. When the version is ready, you can change the version state to Released. When you release a new version of an Event API Product, you may also want to change older versions of the Event API Product to Deprecated or Retired. You must have at least the Event Portal User role with Manager level access to the application domain to change the version state. For more information about version states, see Object Versions and Lifecycle States

You can change an Event API Product version from Draft to Released state only if the Event API Product includes at least one service plan, references at least one event API version, and no referenced event API versions are in draft state.

If a Released version of an Event API Product is publicly available, it can be deprecated or retired but it can't be returned to Draft state.

To change the state of an Event API Product version, perform these steps:

1. On the Application Domains page, click the application domain that contains the Event API Product you want to update.
2. Click Components to switch to the list view.
3. Select the Event API Products tab.
4. Click the name of the Event API Product.
5. Select the version that you want to change the state of, then click Manage Lifecycle.
6. Select the new state.
7. (Optional) If you set the State to Deprecated or Retired, set the End of Life date. If you set a planned or actual End of Life date, the date displays in the version details.
8. Click Save.

Adding an Event API Product to an Environment

You add Event API Product versions to one or more modeled event meshes within an environment to model the deployment of an Event API Product. Before you can make the Event API Product publicly available, you must add it to at least one modeled event mesh. You can add Event API Products to a modeled event mesh, only if the modeled event mesh includes at least one event broker and the event broker has at least one message protocol specified. For more information, see Building a Modeled Event Mesh

To add an Event API Product version to a modeled event mesh, perform these steps:

1. On the Application Domains page, click the application domain that contains the Event API Product you want to add to an environment.
2. Click Components to switch to the list view.
3. Select the Event API Products tab.
4. Click the name of the Event API Product.
5. In the Versions list, select the version that you want to add to a modeled event mesh.
6. In the Event API Product Details pane, click More Actions, then select Add to Environment.
7. Select the Environment that contains the modeled event mesh that you want to add the Event API Product version to.
8. Select a Modeled Event Mesh. The list identifies modeled event meshes that the Event API Product version is already in.
9. Select the Event Broker to add the Event API Product to.
10. Select the Protocols that the event broker uses for connections and exchanging event messages.
11. Click Add.

Making an Event API Product Publicly Available

If you are publishing Event API Products to a third-party API management system or developer portal, you can make an Event API Product version publicly available to publish it.

Before you make the Event API Product version publicly available, you must:

• add the Event API Product to at least one event broker in a modeled event mesh
• change the state of the version to Released

Making an Event API Product version Publicly Available can't be undone. The version can be Deprecated or Retired but it can’t be returned to Draft state.

To make an Event API Product version publicly available, perform these steps:

1. On the Application Domains page, click the application domain that contains the Event API Product.
2. Click Components to switch to the list view.
3. Select the Event API Products tab.
4. Click the name of the Event API Product.
5. In the Versions list, select the version that you want to make publicly available.
6. In the version details, click Make Publicly Available. The option is enabled only if the version state is Released and the version has been added to a modeled event mesh.

Downloading an Async API Document with Event API Product Information

An Async API document is a a JSON or YAML file generated according to the AsyncAPI Specification that describes the contents of an event API. For more information, see the AsyncAPI Initiative. You can give the AsyncAPI document to developers to help them create the actual applications and events that are part of your event mesh.

You can download an AsyncAPI document for an event API in two ways:

• Download a basic AsyncAPI document from the event API page. For more information, see Downloading an AsyncAPI Document for an Event API
• Download a more comprehensive AsyncAPI document that includes service plan details and the server details and operation bindings for any event brokers that the Event API Product has been added to in a modeled event mesh.

To download an AsyncAPI document that includes Event API Product information, perform these steps:

1. On the Application Domains page, click the application domain that contains the Event API Product.
2. Click Components to switch to the list view.
3. Select the Event API Products tab.
4. In the list of Event API Products, click the name of the Event API Product that includes the event API.
5. In the list of included event APIs, click More Actionsfor the event API and select Download Async API.
6. In the Plan list, select a service plan to include details for in the Async API document.
7. In the Event Broker list, select the event brokers to include details for in the Async API document.
8. Select JSON or YAML file format.
9. Click Download File.

Deleting an Event API Product

You can delete an Event API Product version from Designer. When you delete an Event API Product version, it is removed from Designer and from any environments that it has been added to. Any event APIs in the Event API Product remain in Designer.

If you have made the Event API Product publicly available, you must change the version state to Retired before you can delete the version. You can delete an Event API Product with all of its versions only if all publicly available versions are Retired.

To delete an Event API Product, perform these steps:

1. On the Application Domains page, click the application domain that contains the Event API Product.
2. Click Components to switch to the list view.
3. Select the Event API Products tab.
4. Click the name of the Event API Product that you want to delete a version from.
5. In the Versions list, click More Actionsfor the version that you want to delete and select Delete.
6. Click Delete Version.