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 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.
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 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.
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.
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.
- Gloo Edge: By default, Gloo Edge includes External Authorization and Rate Limiting servers.
- Community Istio: The Istio gateway does not provide a server out-of-the-box. Therefore, Gloo Portal deploys its own external auth and rate limiting servers in community Istio setups.
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.