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.dev Pro: An enhanced version of the Lunar.dev Gateway that supports horizontal scaling, allowing deployment across multiple instances for high-traffic scenarios. Redis integration enables shared state management, making Lunar.dev Pro suitable for enterprise environments.

  • Lunar.dev Control Plane: The Lunar.dev Control Plane is a SaaS solution designed to observe, manage, and control API usage within the Lunar.dev 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.

Configuration and Traffic Management

  • Direct Mode: A routing method where HTTP requests are directed through the Lunar.dev Gateway. 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.dev 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.dev 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.dev ecosystem.

  • Lunar.dev Flows: Lunar.dev 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.dev Quotas: Lunar.dev Quotas are configurable limits within the Lunar.dev 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.dev 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.dev 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.dev 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.dev 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.dev 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.dev 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.dev Gateways: The shared state of Lunar.dev Gateways refers to a consistent state across multiple instances of the Lunar.dev API Consumption Gateway. Using shared state components like Redis, Lunar.dev 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.dev Metrics: Lunar.dev Metrics are data points gathered on API traffic and system performance within the Lunar.dev 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.