test.md

Rate Limit API Examples

This document provides curl examples for the MongoDB Atlas Rate Limit Inspection API endpoints with example response bodies.

Overview

The Rate Limit Inspection API provides visibility into rate limiting bucket states for debugging and monitoring purposes. These endpoints are available for different scopes: organization, group, and user.

Authentication

All endpoints require authentication using a Bearer token:

Authorization: Bearer <your-token>

API Version

All endpoints use the 2025-03-12 API version:

Accept: application/vnd.atlas.2025-03-12+json

Endpoints

Organization Rate Limit State

Retrieve rate limiting bucket state for a specific organization.

Request:

curl -X GET \
  "http://localhost:8080/api/atlas/v2/orgs/{orgId}/ratelimit" \
  -H "Accept: application/vnd.atlas.2025-03-12+json" \
  -H "Authorization: Bearer <your-token>"

Example Response:

{
  "scope": "ORGANIZATION",
  "scopeId": "507f1f77bcf86cd799439011",
  "limits": [
    {
      "name": "Rate Limits Inspection",
      "capacity": 100,
      "remaining": 73
    }
  ]
}

Group Rate Limit State

Retrieve rate limiting bucket state for a specific group.

Request:

curl -X GET \
  "http://localhost:8080/api/atlas/v2/groups/{groupId}/ratelimit" \
  -H "Accept: application/vnd.atlas.2025-03-12+json" \
  -H "Authorization: Bearer <your-token>"

Example Response:

{
  "scope": "GROUP",
  "scopeId": "507f1f77bcf86cd799439012",
  "limits": [
    {
      "name": "Rate Limits Inspection",
      "capacity": 100,
      "remaining": 85
    }
  ]
}

Global Rate Limit State (User Scope)

Retrieve rate limiting bucket state for the current user.

Request:

curl -X GET \
  "http://localhost:8080/api/atlas/v2/ratelimit" \
  -H "Accept: application/vnd.atlas.2025-03-12+json" \
  -H "Authorization: Bearer <your-token>"

Example Response:

{
  "scope": "USER",
  "scopeId": null,
  "limits": [
    {
      "name": "Rate Limits Inspection",
      "capacity": 100,
      "remaining": 92
    }
  ]
}

Response Structure

Main Response Object

Field	Type	Description
scope	string	The rate limit scope being inspected (ORGANIZATION, GROUP, USER, or IP)
scopeId	string or null	The identifier for the scope (organization ID, group ID, user ID, or IP address). Can be null for user scope
limits	array	Array of active rate limit bucket configurations and their current states

Rate Limit Bucket State Object

Field	Type	Description	Example
name	string	Name/identifier of the rate limit rule	"Rate Limits Inspection"
capacity	number	Maximum capacity of the token bucket	100
remaining	number	Current number of tokens remaining in the bucket	73

Rate Limiting Disabled

When rate limiting is disabled in the system, all endpoints return a simple string response:

"Rate limiting is disabled"

Error Responses

Internal Server Error

If an error occurs during rate limit state retrieval:

{
  "error": "Internal server error"
}

Notes

• These endpoints are marked as @Hidden in the OpenAPI specification and are intended for debugging and monitoring purposes
• The actual values for capacity and remaining depend on the rate limit configuration and current API usage
• Rate limit scopes follow a hierarchy: GROUP > ORGANIZATION > USER > IP
• The scopeId field will be null for user scope requests as they don't require a specific identifier
• All endpoints require appropriate role permissions (e.g., ORG_OWNER, ORG_READ_ONLY for organization endpoints)

Rate Limit Scope Hierarchy

The system uses the following priority order for determining rate limit scope:

1. GROUP - Takes precedence when a group context is available
2. ORGANIZATION - Used when organization context is available but no group context
3. USER - Applied when user is authenticated but no group/organization context
4. IP - Fallback scope for unauthenticated requests or when no other scope is available

Example Usage Scenarios

Monitoring Organization Rate Limits

# Check rate limit status for organization
curl -X GET \
  "http://localhost:8080/api/atlas/v2/orgs/507f1f77bcf86cd799439011/ratelimit" \
  -H "Accept: application/vnd.atlas.2025-03-12+json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Debugging Group Rate Limits

# Check rate limit status for a specific group
curl -X GET \
  "http://localhost:8080/api/atlas/v2/groups/507f1f77bcf86cd799439012/ratelimit" \
  -H "Accept: application/vnd.atlas.2025-03-12+json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

User Rate Limit Status

# Check current user's rate limit status
curl -X GET \
  "http://localhost:8080/api/atlas/v2/ratelimit" \
  -H "Accept: application/vnd.atlas.2025-03-12+json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."