Group API Quota by Header

Group API Quota by Header enables dynamic quota allocation based on user roles by grouping requests using the x-user-role header. This allows you to set varying limits for different user types under a shared total quota.

Use Cases

1. Use Case - unique limits

This setup is ideal when different user roles need varying levels of access to API resources, ensuring that privileged users (like admins) have more generous limits, while less privileged users (like guests) are more restricted.

Key Highlights:

• Total Quota: The main quota (RoleBasedQuota) limits the total number of requests across all roles to 100,000 per month.
• Group by Header: The group_by_header field is used to segment this quota based on the value of the x-user-role header.
  • admin users get a higher share (5,000 requests per day).
  • user roles get a moderate share (4,000 requests).
  • guest users are restricted to only 1,000 requests per day.

/etc/lunar-proxy/quotas/{fileName}.yaml

quotas:
  - id: RoleBasedQuota
    filter:
      url: api.website.com/* # Apply to all API endpoints under this URL pattern
    strategy:
      fixed_window:
        static:
          max: 100000 # Maximum requests allowed in total
          interval: 1 # Quota resets every day
          interval_unit: month
          group_by_header: x-user-role # Grouping by the 'x-User-Role' header

internal_limits:
  - id: AdminQuota
    parent_id: RoleBasedQuota # Links this quota to the main quota
    filter:
      headers:
        - key: x-user-role
          value: admin # Quota for 'admin' users
    strategy:
      fixed_window:
        static:
          max: 5000 # Admins get half of the total quota
          interval: 1
          interval_unit: day

  - id: UserQuota
    parent_id: RoleBasedQuota
    filter:
      headers:
        - key: x-user-role
          value: user # Quota for 'user' role
    strategy:
      fixed_window:
        static:
          max: 4000 # Regular users get 4000 requests
          interval: 1
          interval_unit: day

  - id: GuestQuota
    parent_id: RoleBasedQuota
    filter:
      headers:
        - key: x-user-role
          value: guest # Quota for 'guest' users
    strategy:
      fixed_window:
        static:
          max: 1000 # Guests get the remaining 1000 requests
          interval: 1
          interval_unit: day

2. Use Case - equal limits

All headers share the same limit. The group_by_header field is used to segment this quota based on the value of the x-user-role header. In the following example, each x-user-role is allowed 12 requests per minutes.

/etc/lunar-proxy/quotas/{fileName}.yaml

quotas:
  - id: EqualQuotaHeaderBased
    filter:
      url: api.website.com/*
    strategy:
      fixed_window:
        max: 12
        interval: 1
        interval_unit: minute
        group_by_header: 'x-api-key'