API Bundle

API Bundles allow you to group one or more APIs together, enabling efficient management through Plans.

API Bundle behaviour

An API Bundle acts as a facade for one or more APIs. Wherever an API can be referenced, an API Bundle can be referenced as well. This feature enables:

• Grouping multiple APIs under a single entity.
• Applying API Plans to API Bundles i.e governing rate limits and quotas across all included APIs.

Note

An API Bundle cannot include another API Bundle.

Creating an API Bundle

You can define an API Bundle using the APIBundle custom resource (CR). Currently, There are two ways to include APIs in a bundle:

By Explicit API Names

apiVersion: hub.traefik.io/v1alpha1
kind: APIBundle
metadata:
  name: my-bundle
  namespace: your-namespace
spec:
  apis:
    - name: api-weather
    - name: api-forecast

By Label Selector

apiVersion: hub.traefik.io/v1alpha1
kind: APIBundle
metadata:
  name: my-bundle
  namespace: your-namespace
spec:
  apiSelector:
    matchLabels:
      category: weather

• Explicitly defining the API name directly lists the APIs (api-weather and api-forecast) to include in my-bundle.
• Using the label selector method allows you to dynamically bundle APIs without listing each one explicitly.

Granting access to an API Bundle

Use the APIAccess resource to grant users or groups access to an API Bundle.

apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: access-to-my-bundle
  namespace: your-namespace
spec:
  # Grant access to every authenticated user
  everyone: true
  # or specify user groups
  # groups:
  #   - name: External
  apiBundles:
    - name: my-bundle
  apiPlan:
    name: std-plan

API Bundle example use cases

Use Case 1: Partner access to bundled APIs

Scenario: You have two APIs, Weather and Forecast, that you want to offer to your partners as a single bundle called WeatherBundle. You wish to enforce a rate limit of 10 requests per second and a monthly quota of 1,000 requests.

API Bundle

This bundle, named weather-bundle, explicitly lists api-weather and api-forecast as the APIs it includes

apiVersion: hub.traefik.io/v1alpha1
kind: APIBundle
metadata:
  name: weather-bundle
  namespace: your-namespace
spec:
  apis:
    - name: api-weather
    - name: api-forecast

API Plan

The std-plan enforces a rate limit of 10 requests per second and a monthly quota of 1,000 requests

apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
  name: std-plan
  namespace: your-namespace
spec:
  title: "Standard Plan"
  description: "**Standard Plan with rate limits and quotas**"
  rateLimit:
    limit: 1
    period: 1s
  quota:
    limit: 10000
    period: 750h # Approximately one month

API Access

An APIAccess resource to grant the External user group access to the bundle using the defined plan.

apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: access-for-external
  namespace: your-namespace
spec:
  groups:
    - name: External
  apiBundles:
    - name: weather-bundle
  apiPlan:
    name: std-plan

Resulting behavior

• Partners in the External Group: When these partners access the Developer Portal, they will see the Weather Bundle available to them.
• Shared Rate Limits and Quotas: All APIs within weather-bundle share the same rate limits and quotas defined by std-plan because it's given through the same api access.
• Quota Renewal: After consuming 10,000 requests, access is blocked until the quota renews in the next period.

Use Case 2: Internal developers with access to individual APIs and bundles

Scenario: Internal developers need access to all APIs, including an Admin API, with higher rate limits and quotas. The Admin API should be accessible both individually and as part of a bundle.

Weather API

apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
  name: api-weather
  namespace: your-namespace
spec: {}  # Additional specifications for the Weather API

Forecast API

apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
  name: api-forecast
  namespace: your-namespace
spec: {}   # Additional specifications for the forecast API

Admin API

apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
  name: api-admin
  namespace: your-namespace
spec: {} # Additional specifications for the admin API

API Bundle

The website-apis bundle includes api-weather, api-forecast, and api-admins

apiVersion: hub.traefik.io/v1alpha1
kind: APIBundle
metadata:
  name: website-apis
  namespace: your-namespace
spec:
  apis:
    - name: api-weather
    - name: api-forecast
    - name: api-admin

API Plan

The internal-plan provides a higher rate limit (50 requests per second) and the same monthly quota as the standard plan.

apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
  name: internal-plan
  namespace: your-namespace
spec:
  title: "Internal Plan"
  description: "**Higher limits for internal developers**"
  rateLimit:
    limit: 50
    period: 1s
  quota:
    limit: 10000
    period: 750h # Approximately one month

API Access

The internal-plan provides a higher rate limit (50 requests per second) and the same monthly quota as the standard plan.

apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: access-for-internal
  namespace: your-namespace
spec:
  groups:
    - internal
  apiBundles:
    - name: website-apis
  apis:
    - name: api-admin
  apiPlan:
    name: internal-plan

Resulting behaviour

• Multiple Access Points: Developers can access the Admin API either through the website-apis bundle or directly via api-admin.
• Higher Limits: partners benefit from the higher rate limits specified in the internal-plan.

Use Case 3: Users in multiple groups with different access levels

Scenario: Some users belong to both the external and vip groups. You want VIP users to have higher rate limits and quotas when accessing WeatherBundle.

API Plan

The extra-plan offers higher rate limits (20 requests per second) and quotas for VIP users

apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
  name: extra-plan
  namespace: your-namespace
spec:
  title: "VIP Plan"
  description: "**Enhanced limits for VIP users**"
  rateLimit:
    limit: 20
    period: 1s
  quota:
    limit: 20000
    period: 750h # Approximately one month

API Access for VIP users

The internal-plan provides a higher rate limit (50 requests per second) and the same monthly quota as the standard plan

apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: access-for-vip
  namespace: your-namespace
spec:
  groups:
    - vip
  apiBundles:
    - name: weather-bundle
  apiPlan:
    name: extra-plan
  weight: 2

API Access for External Users

This is the existing access for the external group, with a higher weight value (1), giving it lower priority compared to the VIP access

apiVersion: hub.traefik.io/v1alpha1
kind: APIAccess
metadata:
  name: access-for-external
  namespace: your-namespace
spec:
  groups:
    - external
  apiBundles:
    - name: weather-bundle
  apiPlan:
    name: std-plan
  weight: 1

Resulting behavior

• Priority Determination: Users in both vip and external groups receive access based on the APIAccess resource with the higher weight (higher priority). In this case, access-for-vip has a weight of 2, which takes precedence over access-for-external with a weight of 1.
• Higher Limits for VIPs: VIP users benefit from the higher rate limits and quotas in the extra-plan specifically when accessing the APIs within the weather-bundle, namely api-weather and api-forecast.
• Automatic Selection: At the API level, The system automatically applies the correct plan based on user group memberships and access weights.

Related content

• Learn more about the API object in its dedicated section.
• Learn more about the APIAccess resource in its dedicated section.
• Learn more about the API Portal in its dedicated section.
• Learn more about User Management in its dedicated section.