Skip to main content
Version: 1.0.x

Terminology

Core Components

  • API Consumption Gateway: Lunar.dev’s primary component for managing outbound API traffic, allowing users to route, control, and secure API requests to external services. It includes built-in flows and quotas, optimizing API usage while minimizing latency.

  • Lunar Pro: An enhanced version of the Lunar Gateway that supports horizontal scaling, allowing deployment across multiple instances for high-traffic scenarios. Redis integration enables shared state management, making Lunar Pro suitable for enterprise environments.

  • Lunar Control Plane: The Lunar Control Plane is a SaaS solution designed to observe, manage, and control API usage within the Lunar ecosystem. It provides real-time metrics, insights, and detailed controls for API traffic, including dashboards for performance monitoring, flow configurations, and quota and resource management.

  • Lunar Interceptor: A lightweight tool that routes API traffic to Lunar’s API Consumption Gateway without altering the existing codebase. It redirects outgoing requests to the gateway and provides automatic fail-safes.

Configuration and Traffic Management

  • Direct Mode: A routing method where HTTP requests are directed through the Lunar Gateway without requiring interceptor installation. Headers like x-lunar-host and x-lunar-scheme help specify routing details for requests.

  • x-lunar-consumer-tag for Filtering: The x-lunar-consumer-tag is a custom HTTP header that labels API requests by application, service, or user group, enabling the Lunar Control Plane to filter and organize requests based on tag values. This segmentation enhances traffic visibility and simplifies management across different segments.

  • x-lunar-consumer-tag for Flow Configuration: By utilizing x-lunar-consumer-tag, Lunar Flows can apply targeted configurations, providing precise control over API traffic. This allows users to enforce rules and manage API consumption effectively. The header is removed before forwarding requests to external APIs, ensuring it is used exclusively within the Lunar ecosystem.

  • Lunar Flows: Lunar Flows are configurations written in YAML that control how API requests and responses are processed in real-time. Designed for flexibility, each flow provides a structured way to manage API traffic through a set of customizable rules.

  • Lunar Quotas: Lunar Quotas are configurable limits within the Lunar platform to manage and monitor API consumption across applications, user groups, or environments. Quotas are set in YAML files and can be based on multiple factors, such as URL, HTTP headers, or custom tags, allowing for precise control over API traffic to prevent overuse and ensure equitable distribution of resources.

  • Internal Limits: Internal limits are additional, nested restrictions within a larger quota, set at a more granular level to control API consumption. These limits allow organizations to apply different usage rules for specific segments (e.g., users or services) within an overall quota, helping to ensure efficient resource allocation and avoid surpassing critical thresholds.

  • Failsafe Mechanism: A feature in Lunar that ensures continuous traffic flow to APIs, even during system disruptions, by automatically rerouting traffic when the gateway is unavailable.

  • Path Parameters: Path Parameters are reusable, dynamic segments in API URLs that allow for grouping similar endpoints under one path pattern. By configuring path parameters, Lunar can apply consistent policies across variable segments in API endpoints, making traffic management more efficient and structured.

Flows Components

  • API Streams: API Streams represent the continuous flow of data in the form of API requests and responses. Lunar segments this traffic into request streams and response streams, which can be further divided into sub-streams using filters. These streams help manage specific traffic segments, allowing for customized processing within Lunar Flows.

  • API Stream Filter: An API Stream Filter is a criterion used to segment API traffic within a stream, based on parameters like URL, HTTP method, or headers. Filters help Lunar apply targeted rules to particular traffic segments, ensuring fine-tuned control over API requests and responses according to specific conditions.

  • Flow Processors: Flow Processors are components within Lunar Flows that perform specific actions on API traffic, such as rate-limiting, transforming requests, generating responses, or logging data. Processors operate on filtered streams and allow for flexible, rule-based traffic management to optimize and control API consumption.

Observability and Metrics

  • Shared State of Lunar Gateways: The shared state of Lunar Gateways refers to a consistent state across multiple instances of the Lunar API Consumption Gateway. Using shared state components like Redis, Lunar Pro instances synchronize their data, such as quotas, metrics, and traffic controls, to provide unified, accurate tracking and management of API consumption across distributed environments.

  • Lunar Metrics: Lunar Metrics are data points gathered on API traffic and system performance within the Lunar platform. Metrics include general traffic statistics (e.g., API call count, size) and internal flow performance indicators (e.g., flow invocation count, execution time). Metrics can be exported to monitoring tools like Prometheus for real-time tracking and analysis.

Additional Concepts
  • CoBo Company: A "Consumers on Behalf of" (CoBo) company is one that consumes APIs on behalf of its clients to deliver added-value services like analytics, threat detection, and optimization. CoBo companies face unique challenges, such as managing shared quotas, handling diverse consumption rates, and ensuring secure, regulated access on behalf of multiple clients.