Event Endpoint Management and IBM API Connect have a number of overlapping concepts, constructs, and terminology. The following glossary aims to describe how these concepts and terminology map between the offerings, or differ where appropriate.
For more information about Event Endpoint Management concepts and constructs, see the key concepts topic.
Terminology
API
API stands for Application Programming Interface. An API defines a contract which describes a service that can be invoked by a client. Depending on the technology or protocols being used, these contracts can be defined and documented in a variety of different ways, such as OpenAPI, used typically for synchronous APIs, or AsyncAPI for asynchronous APIs.
In Event Endpoint Management, Kafka topics are the back-end service being invoked by a client, and are represented as an event endpoint as the API for that topic.
OpenAPI
OpenAPI is the de facto API specification for describing HTTP based API contracts. Typically, these are REST APIs, and provide a synchronous style of interaction with a client.
AsyncAPI
AsyncAPI is an API specification for describing asynchronous API contracts. AsyncAPI has support for a range of protocols, including Kafka, Websockets, JMS, and MQTT. AsyncAPIs are used to define asynchronous interfaces that clients can produce to or consume from. AsyncAPI is becoming the de facto choice to document event-driven architectures.
Management
Management of a socialized API interface is defined by the governance strategy defined by an organization. Aspects of management include the rules of engagement or policies that are enforced by a gateway when using that API, understanding usage, and revoking user access to APIs.
Governance
Governance defines a standardized approach and set of rules that allow the socialization of APIs across an organization. Items to standardize include approaches to versioning, API packaging, but also management concerns at design and runtime.
Multi-form API management
An approach where synchronous and asynchronous APIs can be packaged, managed, and socialized together. This enables scenarios where the same backing service can be exposed in a range of interaction patterns and styles. For example, an order management system can have a synchronous REST API to get all current orders, or an asynchronous Kafka topic which produces events when an order is made. This offers greater choice to the end user to engage with the API in a way that suits them, as well as unifying the governance of these different styles of API in one management experience.
API Connect concepts
The following sections explain key IBM API Connect concepts and components, including how they overlap when an integration is set up with Event Endpoint Management.
API Manager
The API Manager is a user experience in API Connect which provides features for users defined in a provider organization to author and socialize APIs, and to manage API usage.
Event Endpoint Management offers a similar user experience in the Event Manager component, where Kafka topics can be authored and published to become event endpoints. Event endpoints can then be imported into the API Manager as AsyncAPI documents to allow them to be packaged into Products for subsequent socialization and management alongside any other API.
Enforced API
An enforced API is an API which has been included in a Product, published to a Catalog, and has client access enforced by a configured gateway, which applies configured policies to that API.
All event endpoints in Event Endpoint Management are enforced by an Event Gateway.
Unenforced API
An unenforced API is an API which has been included in a Product, published to a Catalog, but the API has been set up to not use any configured gateway to enforce access, or to use any polices.
Currently, there is no direct equivalent concept in Event Endpoint Management. All published event endpoints are enforced.
Policy
A rule, or set of rules, of engagement and behaviors that are enforced by a gateway on a connecting client when using an API. In Event Endpoint Management, these are referred to as controls.
Controls are configured in the Event Manager user experience, included in any imported AsyncAPI document from Event Endpoint Management, and enforced by the Event Gateway.
Gateway
A gateway enforces runtime policies on API traffic, and abstracts the client from the back-end implementation. In API Connect, DataPower Gateways are used to provide synchronous API gateway capabilities. Event Endpoint Management provides the Event Gateway to perform the same role for asynchronous APIs.
When API Connect and Event Endpoint Management are integrated, both types of gateways can be used to enforce API traffic.
Product
A logical grouping of related APIs and Plans to access those APIs. After an AsyncAPI document is imported, the AsyncAPI specification representing the event endpoint from Event Endpoint Management can be added to any Product for publishing later.
Important: Products can only be configured to allow one type of gateway for enforcement.
Note: Currently, there is no direct equivalent Product concept in Event Endpoint Management when not integrated with API Connect.
Plan
An attribute of a Product. Used to offer different levels of service (for example, rate limits and monetization) to the APIs contained within a Product.
Note: Currently, there is no direct equivalent concept in Event Endpoint Management when not integrated with API Connect.
Lifecycle
An API Connect Product, and all the APIs it contains, is managed under a single lifecycle. For a full description of the Product lifecycle, including state transitions, see the API Connect documentation. Any exported AsyncAPI document from Event Endpoint Management representing an event endpoint can be included in a Product, and therefore go through the same Product lifecycle.
Event Endpoint Management has a lifecycle concept applied to an option, which manages the visibility, discovery and use of an event endpoint. The conceptual overlap of API Connect Product lifecycle states with Event Endpoint Management options is as follows:
- Draft - maps to the option ‘Unpublished’ state.
- Staged - maps to the option ‘Unpublished’ state.
- Published - maps to the Option ‘Published’ state.
- Deprecated - maps to the Option ‘Archived’ state.
- Retired - has no equivalent option lifecycle state in Event Endpoint Management.
For more information about the option lifecycle and state transitions, see managing options.
Note: To export an AsyncAPI document from Event Endpoint Management to use with API Connect, an event endpoint must exist. This requires an option that associated with the event source to be shared to be in Published lifecycle state.
Catalog
An API Connect Catalog is both a collection of published Products, the APIs contained within those products, and a management point for those APIs and Products.
Catalog management tasks include configuring Gateways and Developer portal instances to associate with the Catalog. An API Connect Provider organization can contain many Catalogs. Catalogs can also be partitioned into Spaces to offer greater management flexibility.
When the integration is set up between API Connect and Event Endpoint Management, the Event Gateway can be configured as one of the available Gateway Services. As a service, the gateway provides enforcement for any AsyncAPI exported from Event Endpoint Management when the AsyncAPI is published as part of a Product to the Catalog.
Note: Event Endpoint Management also includes the concept of a Catalog. While event authors perform similar API management and usage tasks in the Event Endpoint Management Catalog, the Catalog also provides the equivalent user experience to the API Connect Developer Portal, providing a list of available event endpoints available for others to discover and sign up to use as a source of events.
Space
A Space allows a Catalog to be partitioned or syndicated for management purposes. With Spaces, an individual or team within a Provider organization can manage a selected subset of APIs published to a Developer portal.
Note: Currently, Event Endpoint Management does not have an equivalent concept within its catalog when not integrated with API Connect.
Developer Portal
The runtime component that socializes published Products and the APIs they contain to the wider organization. Users of the Developer Portal will become members of a Consumer organization when they register and create Applications to invoke provided APIs.
When the integration is set up between API Connect and Event Endpoint Management, all APIs that are added to Products will be discoverable, including those from Event Endpoint Management. API usage is managed through the API Manager’s Catalog user experience.
Note: Event Endpoint Management has an equivalent catalog user experience, which is deployed as a part of the Event Manager component. This user experience is available concurrently when integrated with API Connect. However, Subscriptions created in the Event Endpoint Management Catalog are only visible in Event Endpoint Management.
Application
An Application invokes exposed APIs. To use an API, an Application must first be registered by using the Developer portal, through which access credentials are generated for the Application. Applications then register themselves with a Product’s Plans to gain access for invoking the plan’s APIs. A single Application can register with more than one plan.
When the integration is set up between API Connect and Event Endpoint Management, applications registered for Product Plans will have access to event endpoints from Event Endpoint Management.
Note: Event Endpoint Management does not have the concept of an application. Instead, access to event endpoints is provided by unique subscriptions generated on request.
Provider organization
A group within an organization that is responsible for the creation, governance, and management of APIs. When the integration is set up between API Connect and Event Endpoint Management, members of a Provider organization can import any event endpoint from any integrated Event Endpoint Management instance. The integration is configured in the Cloud Manager.
Note: When not integrated with API Connect, Event Endpoint Management does not have a similar concept of an organization to differentiate the provider of an API. Event Endpoint Management is instead configured and deployed by using Kubernetes Operators and custom resources, and user authentication and role management (for example, who can author or view APIs) are configured through these resources.
Consumer organization
A group within an organization who are consuming socialized APIs.
Note: When not integrated with API Connect, Event Endpoint Management does not have a similar concept of an organization to differentiate the consumer of an API. Event Endpoint Management is instead configured and deployed by using Kubernetes Operators and custom resources, and user authentication and role management (for example, who can author or view APIs) is configured through these resources.
Service or Subsystem
A component or microservice that makes up an API Connect instance. These are registered and managed in the Cloud Manager. Event Endpoint Management is integrated with API Connect as an Event Gateway Service.
Note: Event Endpoint Management components are configured, deployed, and managed by using Kubernetes Operators and custom resources.
TLS, Server and Client Profiles
These constructs exist to help configure and manage the configuration between services. They are maintained in the Cloud Manager, and are a required step to configure communication between API Connect and Event Endpoint Management.
Note: Event Endpoint Management does not have an equivalent construct. Instead, Event Endpoint Management is configured, deployed, and managed by using Kubernetes Operators and custom resources.
Cloud Manager
The Cloud Manager is the user experience for configuring and maintaining the resources which combine to make up an API Connect instance (for example, subsystems).
Event Endpoint Management is integrated with API Connect as an Event Gateway Service by using the Cloud Manager tool.
Note: Event Endpoint Management does not have the equivalent of a Cloud Manager tool. Instead, Event Endpoint Management is configured, deployed, and managed by using Kubernetes Operators and custom resources.