Packaging strategy and terminology in API Connect

API Connect uses a proprietary packaging strategy for creating and publishing collections of APIs.

The packaging strategy supports API providers in meeting the requirements of the API consumers. An understanding of the concepts and terminology behind the packaging strategy is required before developing and deploying APIs by using IBM® API Connect.

The following sections describe the concepts and terminology behind the packaging strategy for IBM API Connect:

APIs

An Application Programming Interface (API) is an industry-standard software technology. An API is a set of routines, protocols, and tools for building software applications. An API specifies how software components interact and provides quick access to common assets and processes. APIs can be public (such as offered on GitHub), can require client credentials, or can be kept private within an application. Thus, APIs are classified as external (public), partner (protected), or internal (private), based on how they are consumed.

An API is composed of operations, called methods, which are offered in one of the following styles in API Connect:
  • A REST API is structured according to the principles of Representational State Transfer. REST APIs use HTTP or HTTPS requests to PUT, GET, POST, and DELETE data (also referred to as CRUD operations). REST identifies resources using URIs. Data can be described in a variety formats (XML, HTML, JSON, TXT, etc.), with JSON being the popular choice. REST APIs specify MIME (Multipurpose Internet Mail Extensions) types. REST is platform- and language-independent and works across firewalls using HTTPS. REST APIs leverage HTTP standards for security, caching, and status codes. HTTP clients and servers are available for all major programming languages and operating system/hardware platforms. REST implementations are easily scaled due to use of HTTP and browsers as a uniform interface.
  • A SOAP (Simple Object Access Protocol) API is a web service that is exposed as an API. SOAP interfaces are described in WSDL (Web Services Description Language) format. The WSDL is an XML document describing the structure for headers, messages, URL endpoints, and data types used to access a web service.

APIs can be versioned and packaged into multiple products for distribution to API consumers on the Developer Portal. For information about creating and managing APIs, see Developing your APIs and applications and Managing your APIs.

Plans and products

Plans and products are proprietary packaging constructs that are unique to API Connect. API providers use products to offer one or more APIs to the application developers who consume the APIs (API consumers). Providers use plans to control access to APIs and to manage API usage. Products are packages that contain APIs and the accompanying plans. For more information on Plans and products, see Working with API products and plans.

To make an API available to an application developer, it must be included in at least one product and associated with at least one plan.

Plans

Plans perform the following functions:

  • Control which APIs an application developer can access
  • Make available a collection of operations from one or more APIs
  • Apply quotas to control API usage.
  • Apply rate limits, for supported gateways, to control traffic bursts and differentiate offerings.
  • Define how many requests a consuming application can make within a specified time interval
Quota

A quota defines the total number of requests that a consuming application can make during a specified time interval. A quota can be applied as a default value that is shared across all operations in a plan, or it can be set for specific operations of an API.

Rate limit

A rate limit controls the burst of incoming traffic by restricting the rate at which requests are processed, such as requests per second or requests per minute.

Rate limits are applied at the plan level and are used to prevent sudden spikes in traffic from overwhelming backend services. Rate limits are supported only for specific gateways and cannot be overridden at the API or operation level.

Plans can use differing quotas and rate limits to provide different levels of service to API consumers. For example, a Demo Plan might enforce a low quota and rate limit, while a Full Plan might permit significantly higher usage.

Products

A product in API Connect bundles a set of APIs and plans into one offering that is intended for a particular use. Products are published to a Catalog, where application developers can discover them.

Relationship between products and plans
The following rules apply for the relationship between products and plans:
  • A product can include multiple plans, each defining a different level of access or performance and a specific set of APIs.
  • A plan can share APIs with plans from other products.
  • Multiple plans within a single product can represent different offerings. For example, a product can include a Demo Plan that exposes a limited set of APIs and a Full Plan that exposes all APIs.
Gateway-specific behavior

Plan behavior differs based on the gateway type:

  • DataPower API Gateway
    • Supports both quota and rate limit.
    • A plan can expose all APIs in a product or a subset of APIs.
    • Quota is defined at the plan level and can be overridden at the operation level.
    • Rate limit is defined only at the plan level and cannot be overridden.
  • DataPower Nano Gateway
    • Supports quota only.
    • A plan can expose all APIs in a product or a subset of APIs.
    • Quota is defined at the plan level and can be overridden at the operation level.

Example: plans, APIs, and limits

The following example illustrates plan behavior for DataPower API Gateway and DataPower Nano Gateway.

Selection of operations and rate limits in a plan
The diagram illustrates the following concepts:
  • Product A contains two APIs and two plans.
  • Both APIs are included in Plan A1.
  • Plan A2 includes only API 2, which is also included in Plan A1. Operation 2a for API 2 is excluded from Plan A1. All operations in API 2 are included in Plan A2.
  • Different quotas are set for the two plans at the plan level. For API 2 in Plan A2, a quota is also set specifically for Operation 2c to override the quota set at the Plan level.

Products are used to manage the lifecycle of the APIs they contain. The states in the Product lifecycle include draft, staged, published, deprecated, and retired. A product moves to the published state when the product is published. The APIs in a product become accessible to API consumers when the product is in the published state and they then become visible on a CMS Portal or Developer Portal. After a product is published, application developers can use the CMS Portal or Developer Portal to gain access to its APIs by registering applications to one or more plans in the product.

The following diagram illustrates the hierarchy of products, plans, and APIs.
Hierarchy of products, plans, and APIs

For more information about managing the lifecycle of products, see Working with products.

Catalogs and Spaces

A Catalog contains a collection of products. Catalogs are staging targets through which products (together with the accompanying plans and APIs) are published on a CMS Portal. Catalogs are used to separate products and APIs for testing before publishing them on a CMS Portal. In a typical workflow, an API provider uses a development Catalog when developing and testing APIs, and uses a production Catalog for publishing APIs that are ready for external use. Each Catalog has an associated CMS Portal for exposing the published products. A Catalog includes runtime capability through an associated gateway service that handles any API requests for the APIs in that Catalog.

API Connect includes a syndication feature that enables API providers to partition a Catalog into multiple staging targets (or Spaces) for API development purposes. Each API provider development team can use its own dedicated Space to manage its products independently of other teams. A Space has its own set of capabilities relating specifically to the products and APIs that are created and published to that Space. Products and APIs in all Spaces in a given Catalog are published to the same CMS Portal. Spaces are not visible on the Developer Portal. Application developers who consume the APIs on the CMS Portal are unaware of the Space configuration used by the API Developers. On the CMS Portal, the APIs are seen as a coordinated offering within a Catalog.

For more information about Catalogs and Spaces, see Working with Catalogs and Using syndication to partition Catalogs into Spaces.

Organizations and users

In the context of API Connect, there are two types of organizations: provider and consumer. An organization can encompass a project team, department, or division.

A provider organization owns APIs, and associated plans and products, and can additionally own provider applications that are called by APIs. To complete the various functions in the API lifecycle, a provider organization assigns responsibilities for certain tasks. Some standard responsibilities within a provider organization include:
  • A provider organization owner who has the full set of access permissions to API Connect functions, and can also commission APIs and track their business adoption.
  • API developers who design and develop APIs and applications for the provider organizations to which they belong.
  • An administrator who manages the lifecycles of APIs and publishes APIs for discovery and use.
  • A community manager who manages the relationship between the provider organization and application developers, provides information about API usage, and provides support to application developers.
A consumer organization owns only developer applications, and consumes the APIs and applications produced by the provider organization. Standard responsibilities within a consumer organization include:
  • A consumer organization owner who adds application developers to the consumer organization, views the products and APIs that the provider organization has made available on the CMS Portal, and subscribes to APIs to use them in applications.
  • Application developers who view the products and APIs that the provider organization has made available on the CMS Portal, and subscribe to use these APIs in applications.

Users have an existence in the API Connect ecosystem that is independent of an organization. A user can be a member of more than one provider or consumer organization.

There can be multiple provider organizations in one API Connect cloud, to provide an API development environment for each line of business of an enterprise. The API Connect cloud is a collection of servers that comprise an API Connect installation, including the configuration information and metadata that they contain. The cloud infrastructure is shared by all organizations, and managed independently of them (by an IBM Operations team). The following diagram shows the relationship between the provider organizations, consumer organizations, and users.
Diagram showing the relationship between the provider organizations, consumer organizations, and users.

For more information about organizations, see Administering consumer organizations.

Sample provider organization with two Catalogs

The following diagram shows an example for how APIs, plans, products, Catalogs, and Spaces fit within provider and consumer organizations. In this example, two Catalogs are created in the provider organization to act as staging targets for different sets of requirements.
  • Catalog 1 does not require separation of the products for use by individual provider development teams, and so does not have Spaces enabled. API developers with access to this Catalog create draft APIs, and stage and publish them as products to the Catalog. Several consumer organizations are granted permission to explore, discover, and use the published products and APIs. In each of the consumer organizations, the published products and APIs from Catalog 1 are exposed on a single CMS Portal.
  • Catalog 2 is partitioned into two Spaces (X and Y) so that two provider development teams can manage their products independently. These teams stage and publish their APIs (as products) separately to the individual Spaces, to make them accessible to application developers in multiple consumer organizations. In each of the developer organizations, the published products and APIs from both Spaces are exposed in the same CMS Portal, and application developers who access this portal will see the APIs from both Spaces as a coordinated offering.
Hierarchy for organizations, Catalogs, Spaces, products, plans, and APIs