Skip to main content

API Gateway Overview

The citadel/apps/api-gateway directory in this monorepo serves a crucial role in defining and validating the contract for our API Gateway. It is important to understand that this directory does NOT contain the actual API Gateway implementation. Instead, it houses a comprehensive suite of Behave Python tests that ensure any API Gateway deployed in front of Citadel adheres to the expected behaviors and security policies.

By default, and for ease of configuration and scalability from docker-compose to Kubernetes environments, we recommend and utilize Traefik Proxy as our API Gateway. Traefik's configuration, often managed via YAML files or Kubernetes labels, allows for flexible and robust routing, load balancing, and middleware application.

API Gateway as a Contract​

The tests within citadel/apps/api-gateway define the "contract" that any API Gateway must fulfill. This approach provides several benefits:

  • Interoperability: Users can swap out Traefik for their own preferred API Gateway solution (e.g., Nginx, Envoy, Kong) as long as it satisfies the behaviors validated by these tests.
  • Consistency: Ensures consistent behavior across different deployment environments and gateway implementations.
  • Test-Driven Development: New API Gateway features or changes to existing policies are first defined as Behave scenarios, ensuring clear requirements and automated validation.

Key Contracted Behaviors​

The Behave tests cover critical aspects of API Gateway functionality, including but not limited to:

  • Authentication: Verification or introspection of tokens (JWT or opaque), handling of missing/invalid tokens. Note: The API Gateway verifies tokens but does not create "enriched JWTs" - it adds authorization claims as HTTP headers to requests.
  • Authorization: Enforcement of access control policies, with support for both standard mode (gateway verifies and adds headers) and zero-trust mode (gateway passes auth header through to downstream services).
  • CORS: Correct handling of Cross-Origin Resource Sharing.
  • Rate Limiting: Application and enforcement of request rate limits.
  • Circuit Breaking: Behavior when upstream services are unhealthy.
  • IdP Discovery: Logic for identifying Identity Providers based on request context.
  • Caching: Verification of caching mechanisms for performance optimization.

For detailed scenarios and step definitions, refer to the .feature files and corresponding Python step implementations within citadel/apps/api-gateway/tests/.