Skip to main content

Catalog External APIs

Traefik Hub can list and document APIs that are not routed through the Hub gateway. This lets you host internal and external API docs together (for example Stripe, AWS API Gateway, or Oracle Integration Cloud) without changing where those APIs run.

You can also run a portal-only experience with Traefik Hub: no IngressRoute is required for APIs, and you do not need an APIPlan for this scenario.

How It Works​

  • Choose your model:
    • Versioned: Create one or more APIVersion resources that point to an external OpenAPI specification and override the server URL to the live endpoint you want to show in the portal, then bind them in an API.
    • Single current version: Define a single API with openApiSpec and update the upstream OAS as it evolves. This is useful when the provider only exposes “current” docs.
  • Publish them to the Developer Portal with an APICatalogItem (no plan needed).
  • Optionally, add an APIBundle to keep external APIs grouped separately from internal ones.

Example: Catalog External HTTPBin​

Create two API versions that pull OAS files from a URL (GitHub, Gist, static file server, etc.) and override the server to the live host:

apiversions.yaml
apiVersion: hub.traefik.io/v1alpha1
kind: APIVersion
metadata:
  name: httpbin-v1
  namespace: apps
spec:
  title: "HTTPBin API"
  description: "HTTPBin API OpenAPI spec"
  release: v1.0.0
  openApiSpec:
    url: https://raw.githubusercontent.com/carlosvillanua/apiops/refs/heads/main/httpbin_no_ingress/oas/httpbin_v1_OAS.yaml
    override:
      servers:
        - url: https://httpbingo.org/
---
apiVersion: hub.traefik.io/v1alpha1
kind: APIVersion
metadata:
  name: httpbin-v2
  namespace: apps
spec:
  title: "HTTPBin API"
  description: "HTTPBin API OpenAPI spec"
  release: v2.0.0
  openApiSpec:
    url: https://raw.githubusercontent.com/carlosvillanua/apiops/refs/heads/main/httpbin_no_ingress/oas/httpbin_v2_OAS.yaml
    override:
      servers:
        - url: https://httpbingo.org/

Create the API that references those versions:

api.yaml
apiVersion: hub.traefik.io/v1alpha1
kind: API
metadata:
  name: httpbin-api
  namespace: apps
spec:
  title: "HTTPBin API"
  description: "HTTPBin API OpenAPI spec"
  versions:
    - name: httpbin-v1
    - name: httpbin-v2

Publish the API to the portal with an APICatalogItem:

catalogitem.yaml
apiVersion: hub.traefik.io/v1alpha1
kind: APICatalogItem
metadata:
  name: httpbin
  namespace: apps
spec:
  everyone: true
  apis:
    - name: httpbin-api

After applying these manifests, the HTTPBin documentation appears in the Developer Portal and the live server URL points to https://httpbingo.org/ as defined by the override.servers section. If the API’s CORS policy allows it, you can call the API directly from the portal. Make sure to add the required auth credentials if the API enforces authentication.

Organize External vs Internal APIs​

  • Use an APIBundle to group external APIs so they stay separate from internally routed APIs in the portal.
  • Create separate APICatalogItem resources per audience (for example, one for external partners, one for internal teams) to keep visibility clear.
bundle.yaml
apiVersion: hub.traefik.io/v1alpha1
kind: APIBundle
metadata:
  name: external-apis
  namespace: apps
spec:
  title: "External APIs"
  apis:
    - name: httpbin-api      # External API defined above
    - name: stripe-api     # Add other external APIs you have defined
---
apiVersion: hub.traefik.io/v1alpha1
kind: APICatalogItem
metadata:
  name: external-apis-catalog
  namespace: apps
spec:
  everyone: true
  apiBundles:
    - name: external-apis

With this bundle, all external APIs stay together and can be shown in one portal without mixing with internal APIs. Add more APIs to the bundle as you define them.

Portal-Only Operation​

  • You can skip the IngressRoute configuration for these APIs; the portal renders docs from the OpenAPI sources.
  • If you later want gateway controls (auth, rate limiting, observability), add routing and plans without changing the catalog structure.
  • When you introduce gateway routing for these external APIs and need to pass provider-specific credentials upstream, see Upstream Authentication for header/token injection patterns.

Example: Portal-Only Catalog (No Gateway Traffic)​

You can expose the Developer Portal without routing any APIs through Traefik Hub. The portal renders the OpenAPI specs you defined and hits the external servers directly.

apiVersion: hub.traefik.io/v1alpha1
kind: APIPortal
metadata:
  name: external-portal
  namespace: apps             # Must match the namespace of your APICatalogItem
spec:
  title: "External APIs Portal"
  description: "Docs for externally hosted APIs"
  • This exposes only the portal; no API traffic goes through the Hub gateway.
  • kubernetesIngress supports cross-namespace service references by default, so the Ingress in apps can target the apiportal service in traefik. If you prefer IngressRoute, enable providers.kubernetesCRD.allowCrossNamespace=true or co-locate the APIPortal and APICatalogItem with the service.

Related Content​