API Management

Managing APIs with Gloo Portal happens through the use of three resources: API Doc, API Product, and Environment.

The fundamental thing to understand is that Environments contain one or more API Products, along with the Usage Plans to control things like access, authentication, and rate limiting for each API Product. API Products have multiple versions, each referencing API Docs and the operations they contain. API Docs define operations and are referenced in one or more API Product versions. The following diagram shows how the three resources are related to each other.

API product architecture

API Docs

API Docs are a Kubernetes Custom Resource which packages the API definitions maintained by the maintainers of an API. Each API Doc maps to a single Swagger Specification. The APIs endpoints themselves are provided by backend services.

Each API Doc contains the definitions for the individual API operations available to be published as part of an API Product.

API Docs Screenshot

Developers can present the Gloo Portal administrator with their OpenAPI specifications without needing to know where the service backing the spec is deployed.

Read the full API Doc Spec here

API Products

API Products are a Kubernetes Custom Resource which bundles the APIs defined in API Docs into Versions. The API product can have multiple versions defined, each with their own references to API Docs and APIs selected from those API Docs.

Product owners specify the API Docs and operations they wish to bundle into a Version inside their API Products. The Versions also define the routing to reach an implementation of the APIs on a backend service.

API Products Screenshot

Read the full API Product Spec here


An Environment represents information about a set of domains that serve a set of API Product versions. Environments control route creation and route-level configuration (e.g. rate limits, user access), which will be exposed to ingress traffic as well as published on a Portal UI.

Each Environment defines Usage Plans per API Product, specifying the tiers of access given to API clients, including how clients are authenticated and rate limited to the APIs they consume.

API Environments Screenshot

Read the full Environment Spec here

API external authorization and rate limiting

When you expose APIs, you want to authenticate and authorize client traffic to the APIs. Such external auth solutions also provide an identity to use for per-client policies such as rate limiting. Rate limiting policies can enforce Service Level Access, prevent Denial of Service attacks, and limit traffic based on access privileges.

Before you can use external auth and rate limiting, you need servers in your Gloo Portal deployment setup.

To configure external auth and rate limiting for GLoo Portal, set up a Usage Plan in the Environment for each API Product. For more information, see the following docs.