Skip to main content
Version: Next

Quick Start with Terminal

Lunar.dev API Consumption Gateway Installation​

Step 1: Install Lunar's Gateway Container​

docker run -d --rm -p 8000:8000 -p 8081:8081 -p 8040:8040 -e TENANT_NAME="ORGANIZATION" -v $(pwd):/etc/lunar-proxy --name lunar-proxy lunarapi/lunar-proxy:latest

CAUTION

Note that the TENANT_NAME environment variable is required. This variable should be set to the name of your organization.

Step 2: Run Post-Installation Health-Check​

curl http://localhost:8040/healthcheck

A correct result should be proxy is up.

Step 3: Pass an API Request​

curl http://localhost:8000/fact -H "x-lunar-host: catfact.ninja" -H "x-lunar-scheme: https"

Then, use the discover command to validate that the requests were passed through Lunar.dev Gateway.

docker exec lunar-proxy discover

Route your API Traffic​

Lunar.dev Gateway allows you to route your HTTP requests through the Lunar.dev Gateway without needing any additional installation.

To route your requests through Lunar.dev Gateway, you need to add these headers:

  • x-lunar-scheme: The original scheme of your request, e.g., https for HTTPS requests.
  • x-lunar-host: The target host, like catfact.ninja.
  • x-lunar-consumer-tag: A unique tag for your app or service. This will be removed before reaching third-party providers.

Change the request URL to route through the Lunar.dev Gateway. Use this format:

http://lunar_proxy_address:lunar_proxy_port/original/request/path

For example, if your Lunar.dev Gateway is at localhost and port 8000, the updated URL for catfact.ninja would look like this:

curl http://localhost:8000/fact -H "x-lunar-host: catfact.ninja" -H "x-lunar-scheme: https"

After adding the headers and adjusting the URL, send the request. Lunar.dev Gateway will route it efficiently while keeping the original scheme and host intact.

Configuration​

Configure the flow.yaml and quota.yaml files​

After confirming successful installation of lunar.dev, enhance your API consumption with a Lunar.dev Flow.Think of it as a customizable tool that simplifies problem-solving and smoothens API interactions by establishing rules for different scenarios.

In this example, we'll apply the Client side Limiting Flow. Edit the following flow.yaml and quota.yaml files

/etc/lunar-proxy/flows/flow.yaml

name: ClientSideLimitingFlow

filter:
  url: api.website.com/*

processors:
  Limiter:
    processor: Limiter
    parameters:
      - key: quota_id
        value: MyQuota

  GenerateResponseLimitExceeded:
    processor: GenerateResponse
    parameters:
      - key: status
        value: 429
      - key: body
        value: "Quota Exceeded. Please try again later."
      - key: Content-Type
        value: text/plain

flow:
  request:
    - from:
        stream:
          name: globalStream
          at: start
      to:
        processor:
          name: Limiter

    - from:
        processor:
          name: Limiter
          condition: above_limit
      to:
        processor:
          name: GenerateResponseLimitExceeded

    - from:
        processor:
          name: Limiter
          condition: below_limit
      to:
        stream:
          name: globalStream
          at: end

  response:
    - from:
        processor:
          name: GenerateResponseLimitExceeded
      to:
        stream:
          name: globalStream
          at: end

/etc/lunar-proxy/quotas/quota.yaml

quotas:
  - id: MyQuota
    filter:
      url: api.website.com/*
    strategy:
      fixed_window:
        static:
          max: 100
          interval: 1
          interval_unit: minute

In the above example, the plugin will enforce a limit of 100 requests per minute the api.website.com/* API endpoint. If the limit is exceeded, the plugin will return a Lunar-generated API response with 429 HTTP status code.