Skip to main content

API CatalogItem

APICatalogItem is a resource in Traefik Hub that defines which APIs are visible to users in the Developer Portal. It allows API managers to control the visibility of APIs and API Bundles to specific user groups, ensuring that API consumers only see the APIs they are authorized to access.

By using APICatalogItem, you can:

  • Specify which APIs or API Bundles are displayed to specific user groups.
  • Control the visibility of specific operations within APIs.
tip

APICatalogItem focuses on visibility in the Developer Portal, whereas gateway consumption access is managed through ManagedSubscription.

APICatalogItem behavior​

Key Concepts​

  • API: A service exposed via Traefik Hub that can be documented and consumed.
  • API Bundle: A collection of APIs grouped together for easier management.
  • API Plan: Defines the available plans that users can subscribe to when accessing an API.
  • Operation Filter: Allows you to limit the visibility of specific operations within an API.
  • Groups: User groups defined in your Identity Provider (IdP) or Traefik Hub, used to control access.

How APICatalogItem works​

  1. Define APICatalogItem:
  • API Publishers create APICatalogItem resources to specify which APIs or API Bundles are visible to specific user groups.
  • Optionally, limit the visible operations using operationFilter.
  1. User Groups:
  • Users are associated with groups, typically defined in your IdP.
  • APICatalogItem uses these groups to control which users see which APIs.
  1. Developer Portal:
  • Users log into the Developer Portal.
  • They see APIs and API Bundles as defined by the APICatalogItem resources targeting their groups.

Creating an APICatalogItem​

APICatalogItem resources are defined using the Custom Resource Definition (CRD) in Kubernetes. Below is an example of how to create an APICatalogItem.

Example Scenario: Making APIs visible to external partners​

Scenario: You want to make weather-api and forecast-api visible to users in the external group, allowing them to see the APIs on the Developer Portal and subscribe to the standard-plan.

Step 1: Define the APIs​

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

Step 2: Define the API Plan​

apiVersion: hub.traefik.io/v1alpha1
kind: APIPlan
metadata:
  name: standard-plan
  namespace: apps
spec:
  title: "Standard Plan"
  description: "Standard rate limits and quotas"
  rateLimit:
    limit: 10
    period: 1s
  quota:
    limit: 1000
    period: 720h # Approximately 30 days

Step 3: Create the APICatalogItem​

apiVersion: hub.traefik.io/v1alpha1
kind: APICatalogItem
metadata:
  name: external-api-catalog
  namespace: apps
spec:
  groups:
    - external
  apis:
    - name: weather-api
    - name: forecast-api
  apiPlan:
    name: standard-plan
Configuration Options​
FieldDescriptionRequired
groupsA list of user groups that will see the APIs.Yes
everyoneA boolean indicating that all users will see the APIs.No
apisA list of APIs to be made visible.Yes
apiPlanThe API plan that defines the consumption policies for the APIs.Yes
apiSelectorA label selector to dynamically include APIs based on labels.No
apiBundlesA list of API Bundles to be made visible.No
operationFilterLimits the visible operations within the APIs.No

Outcome​

portal.localhost

Developer Portal

  • Users in the external group can see weather-api and forecast-api on the Developer portal.

Using API Bundles​

If you have APIs grouped into an APIBundle, you can include the bundle in the APICatalogItem.

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

Outcome​

  • Users in the external group can see all APIs within the weather-bundle in the Developer portal.

API Selector​

You can use apiSelector to dynamically include APIs based on labels in your Managed Subscriptions.

apiVersion: hub.traefik.io/v1alpha1
kind: APICatalogItem
metadata:
  name: weather-api-catalog
  namespace: apps
spec:
  groups:
    - external
  apiSelector:
    matchLabels:
      category: weather
  apiPlan:
    name: standard-plan
Read More

Please refer to the detailed documentation about Label selectors.

OperationFilter​

You can restrict which operations within an API are visible to users using the operationFilter option.

apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
  name: my-api
  namespace: apps
spec:
  openApiSpec:
    path: /openapi.yaml
    operationSets:
      - name: get-employees
        matchers:
          methods: ["GET"]
          path: "/employees"
      - name: get-payrolls
        matchers:
          methods: ["GET"]
          path: "/payrolls"

Frequently Asked Questions​

  • How does APICatalogItem differ from ManagedSubscription?

    • APICatalogItem: Controls visibility of APIs and API Bundles on the Developer Portal for specific user groups.
    • ManagedSubscription: Grants gateway consumption access to applications, specifying which applications can consume which APIs under which plans.

  • Can I use both groups and everyone in APICatalogItem?

    No, groups and everyone are mutually exclusive. You should use one or the other.

  • Is there a limit to the number of APIs and API Bundles in an APICatalogItem?

    Yes, you can specify up to 100 APIs and 100 API Bundles per APICatalogItem. However, this limit is only on the apis and apiBundles fields, you can select as many objects as you wish with selectors.

Related content​