Event APIs

Event APIs allow you to curate the event data that you've designed or imported together into packages that you can share with others to use to build new applications. Event APIs can be shared with application developers by generating and sharing an AsyncAPI document, which is a JSON or YAML file generated according to the AsyncAPI Specification. For more information, about AsyncAPI documents, see the AsyncAPI Initiative.

An event API bundles together the following information:

  • shared events that you want to provide to other application developers
  • associated schema information
  • information about the event operation (publish and/or subscribe)

You can also add event APIs to Event API Products.

This section includes the following tasks:

You can also create custom attributes for event APIs. For more information, see Using Custom Attributes

Creating an Event API

You create event APIs within application domains. Events must be shared to add them to an event API, even if they are in the same application domain.

To create an event API, 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 to.
  4. Click Components to switch to the list view.

  5. Select the Event APIs tab, then click Create Event API.

    Screenshot showing the settings described in the surrounding steps.

  6. Enter a Name for the event API.
  7. Select the Broker Type. You can't change the broker type after you save the event API.
  8. If you want the event API to be available in other application domains or you want to add it to an Event API Product, select Allow Event API to be shared across application domains.
  9. In the Version field, specify a semantic version value for the event API 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.
  11. (Optional) Enter a Description for the event API. The Description field supports Markdown. Click toggle preview to preview the rendered text.
  12. (Optional) Add values for any custom attributes that have been set up in your organization.
  13. To select events to include in the event API, perform these steps:
    1. Click Manage Events.
    2. In the Application Domain list, select the application domain for an event that you want to add to the event API. By default, the list shows shared events in the current application domain. If you select a different application domain, the list shows shared events in the selected application domain. If you remove the filter, the list shows shared events in all application domains that you have access to.
    3. Expand an event to see the list of versions.
    4. To allow an external application to subscribe to a version of an event, select Sub for the event version.
    5. To allow an external application to publish a version of an event, select Pub for the event version.
    6. When you are finished selecting events, click Close .
  14. Click Save Event API.

Downloading an AsyncAPI Document for an Event API

An AsyncAPI document is a a JSON or YAML file generated according to the AsyncAPI Specification that describes the contents of your 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.
  • Download a more comprehensive AsyncAPI document that includes service plan details and the server details and operation bindings for any event brokers that are associated with an Event API Product that the event API is part of. For more information, see Downloading an Async API Document with Event API Product Information

To download a basic AsyncAPI document for your event API, perform these steps:

  1. On the Application Domains page, click the application domain that contains the event API.
  2. Click Components to switch to the list view.
  3. Select the Event APIs tab.
  4. In the list of event APIs, click the name of the event API.
  5. In the Versions list, select the version that you want to download the AsyncAPI document for.
  6. In the version details, click More Actions and select Download Async API.
  7. Select JSON or YAML file format.
  8. Click Download File.

Updating an Event API

When you update an event API, you can update an existing version or create a new version of the event API. 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, you have three options:

  • If the event API version is in Draft state, you can update an existing version and retain the version number
  • If the event API 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 version is in Released, Deprecated, or Retired state, you can create a new version of the event API 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 in the event API, you select the version of the event that you want to include. If a new version of an event is created, you can choose when to update the event API to include the new version.

To update an event API, perform these steps:

  1. On the Application Domains page, click the application domain that contains the event API you want to update.
  2. Click Components to switch to the list view.
  3. Select the Event APIs tab.
  4. In the list of event APIs, click the name of the event API.
  5. Perform one of the following actions:
    • In the Versions list, click More Actions for the version that you want to update and select Edit. Any changes you make update that version of the event API. You can edit an event API version only if it is in Draft state.
    • In the Versions list, click More Actions for 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 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 version as necessary.
  7. Click Save Version or Save & Close.

Changing the State of an Event API Version

When you create a new version of an event API, 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, you may also want to change older versions of the event API 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 only change an event API version from Draft to Released state if the event API references at least one event version and if no referenced event versions are still in draft state

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

  1. On the Application Domains page, click the application domain that contains the event API you want to update.
  2. Click Components to switch to the list view.
  3. Select the Event APIs tab.
  4. In the list of event APIs, click the name of the event API.
  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.