How to Configure API Rate Limit

Overview

The API Rate Limiting feature in ServiceOps helps control the number of API requests made within defined time intervals. This prevents abuse, ensures fair usage, and protects system stability. Configuration is managed using YAML files.

Configuration Files

Rate limiting is configured via the following two files:

Main Service

• Default: /main_service/config/flotomate_rate_limit.yaml
• Custom: /main_service/config/flotomate_rate_limit_custom.yaml

Analytics Service

• Default: /cm-analytics/config/flotomate_rate_limit.yaml
• Custom: /cm-analytics/config/flotomate_rate_limit_custom.yaml

Custom files override default settings without modifying core files.

Basic Configuration Parameters

• enabled: Enables/disables global rate limiting.
• apply-default-rate-limiting: Applies default limits when no group matches a request.
• token-cache-timeout-minutes: Token cache duration (in minutes).
• refill-rate: Tokens added every refill-interval.
• refill-interval: Interval (in seconds) between token refills.
• bucket-capacity: Max number of tokens a bucket can hold.
• initial-bucket-capacity: Initial tokens in a new bucket.

Excluding Routes from Rate Limiting

Use excluded-routes to bypass rate limiting for specific endpoints:

excluded-routes:
  - path: /api/public/organization
  - path: /api/public/ssoconfig/details
  - path: /api/public/supportPortalConfig
  - path: /cm-analytics/config
    methods: [GET]

• Path supports Ant-style wildcards.
• Optionally specify HTTP methods.

Creating API Groups

API groups apply specific rate limits to sets of authenticated routes using tokens from the Authorization header. Example:

api-groups:
  - name: high-volume
    enabled: true
    routes:
      - path: /api/search/**
        methods: [GET, POST]
    bucket-capacity: 100
    refill-rate: 50
    refill-interval: 1
    initial-bucket-capacity: 100

API Group Parameters

• name: Unique name for the group.
• enabled: Enables or disables rate limiting for this group.
• routes: Defines specific routes to apply the rate limit to.
  • path: URL path to restrict (supports wildcards like /**).
  • methods: List of HTTP methods (e.g., GET, POST, DELETE, PATCH).
• bucket-capacity: Maximum number of tokens available for this group.
• refill-rate: Number of tokens added per refill interval.
• refill-interval: Time interval (in seconds) between token refills.
• initial-bucket-capacity: Number of tokens available initially for the group.

Creating Global API Groups

Global API groups allow you to apply rate limits to endpoints that may not have authentication headers or require special handling. They are particularly useful for:

• Applying rate limits to public endpoints
• Controlling access to sensitive operations
• Preventing abuse of public APIs
• Implementing shared rate limits across multiple users

Global API Group Parameters

• name: Unique identifier for the group.
• enabled: Enables or disables rate limiting for this group.
• token: Required token used for rate limiting this group. Must be unique across all global API groups.
• routes: Defines specific routes to apply the rate limit to.
  • path: URL path to restrict (supports wildcards like /**).
  • methods: List of HTTP methods (e.g., GET, POST).
• bucket-capacity: Maximum number of tokens available for this group.
• refill-rate: Number of tokens added per refill interval.
• refill-interval: Time interval (in seconds) between token refills.
• initial-bucket-capacity: Initial number of tokens available for the group.

Example:

enabled: true
apply-default-rate-limiting: false
refill-rate: 20
refill-interval: 1
bucket-capacity: 30
token-cache-timeout-minutes: 30
initial-bucket-capacity: 30

excluded-routes:
  - path: /api/public/organization
  - path: /api/public/ssoconfig/details
  - path: /api/public/supportPortalConfig

api-groups:
  - name: high-volume
    enabled: true
    routes:
      - path: /api/search/**
        methods: [GET, POST]
      - path: /api/list/**
        methods: [GET]
    bucket-capacity: 100
    refill-rate: 50
    refill-interval: 1
    initial-bucket-capacity: 100
    
  - name: low-volume
    enabled: true
    routes:
      - path: /api/admin/**
        methods: [POST, PUT, DELETE]
    bucket-capacity: 10
    refill-rate: 5
    refill-interval: 1
    initial-bucket-capacity: 10

global-api-groups:
  - name: public-api
    enabled: true
    token: public_api_token_xyz
    routes:
      - path: /api/public/**
        methods: [GET, POST]
    bucket-capacity: 10
    refill-rate: 5
    refill-interval: 1
    initial-bucket-capacity: 10
    
  - name: sensitive-operations
    enabled: true
    token: sensitive_ops_token_abc
    routes:
      - path: /api/admin/**
        methods: [POST, PUT, DELETE]
    bucket-capacity: 3
    refill-rate: 1
    refill-interval: 5
    initial-bucket-capacity: 3

Special Client Handling

Rate limits are skipped for:

• Plugin server client
• Analytics service
• Main server service

Rate Limit Headers

When rate limiting is applied, the following headers will be included in responses:

• X-RateLimit-Limit: The maximum number of requests allowed.
• X-RateLimit-Remaining: The number of requests remaining in the current window.
• X-RateLimit-Reset: Time (in milliseconds) until the rate limit resets. These headers allow clients to adjust their request rates and avoid hitting limits.

Apply Changes Without Restart

Use the following endpoints:

• Main Service: POST /system/rate-limiter/refresh

• Analytics Service: POST /analytics/system/rate-limiter/refresh

  Only users with the technician role can perform refresh operations.

Verify Rate Limit Configuration

• Main Service: GET /system/rate-limiter/config
• Analytics Service: GET /analytics/system/rate-limiter/config

Implementation Notes

• Uses Bucket4j library (token bucket algorithm)
• Matches paths using Ant-style wildcards
• Tokens retrieved from Authorization header or global API group token

Quick Steps to Customize Rate Limit Configuration

1. Create a Custom File: Add flotomate_rate_limit_custom.yaml in the appropriate config directory.
2. Copy Default Settings: Duplicate contents from the default file to the custom one.
3. Modify as Needed: Update rate limit parameters, add or change API groups, and save the file.
4. Apply Changes: Use POST /system/rate-limiter/refresh (or analytics variant) to activate changes without restarting.
5. Permissions: Only users with the technician role can apply configuration changes.
6. Verify Configuration: Use GET /system/rate-limiter/config (or analytics variant) to confirm settings.