Skip to main content
Version: 1.0.x

Quick Start with Terminal

Lunar 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 Gateway.

docker exec lunar-proxy discover

Route your API Traffic​

Direct Mode in Lunar Gateway allows you to route your HTTP requests through the Lunar Gateway without needing any interceptor installation.

To route your requests through Lunar 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.

Alternatively, you can use one of the suggested Lunar Interceptors written in Python, Node.JS or Java.

TIP:

Lunar Interceptor needs to be imported to your app. In case you don't have a relevant app in place, refer to our Example Apps

Step 1: Install Lunar Interceptor​

pip3 install --upgrade lunar-interceptor
export LUNAR_PROXY_HOST="localhost:8000"

NOTE

This environment variable sets the host and port for Lunar.dev Gateway. Set this to localhost:8000 if you're running Lunar.dev Gateway in a local Docker container. The value assigned to LUNAR_PROXY_HOST should only include the hostname and port, without the HTTP prefix. For example, use localhost:8000 and not http://localhost:8000.

Step 3: Import Lunar Interceptor to Your App​

import lunar_interceptor
# imports ...

# your code
def main():

Step 4: Run Your App and Validate Proxy/Interceptor Linkage​

Run your app and consume API traffic. Then, use the Discover command to validate that the requests were passed through Lunar.dev Gateway, and that your installed interceptor is correctly listed.

  • Docker
  • Kubernetes
docker exec lunar-proxy discover

Configuration​

Configure the flow.yaml and quota.yaml files​

After confirming successful installation of lunar.dev, enhance your API consumption with a Lunar 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:
        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.

CTRL + M