API Reference

API Reference

Complete REST API documentation for programmatic access to Redis ACL Builder.

---

Base URL

• Development: http://localhost:7380
• Docker: http://localhost:7380 (or your custom port)
• Production: Your deployment URL

---

Content Type

All requests and responses use:

Content-Type: application/json

---

Endpoints

POST /api/parse

Parse an ACL rule and return granted/blocked commands.

Request:

{
  "rule": "+@read -@dangerous ~user:*",
  "version": "redis7"
}

Parameters:

• rule (string, required) - ACL rule to parse
• version (string, required) - Redis version ("redis7" or "redis8")

Response:

{
  "granted_commands": ["get", "mget", "getrange", ...],
  "blocked_commands": ["set", "del", ...],
  "granted_categories": ["@read"],
  "blocked_categories": ["@write", "@dangerous"],
  "key_patterns": ["~user:*"],
  "is_valid": true
}

---

POST /api/test-command

Test if a specific command is allowed by an ACL rule.

Request:

{
  "rule": "+@read",
  "command": "GET",
  "version": "redis7"
}

Response:

{
  "is_granted": true,
  "reason": "Command allowed by @read category",
  "matching_rule": "+@read",
  "categories": ["@read", "@fast", "@string"]
}

---

POST /api/test-command-key

Test if a command + key combination is allowed.

Request:

{
  "rule": "+@read ~user:*",
  "command": "GET",
  "key": "user:123",
  "version": "redis7"
}

Response:

{
  "command_allowed": true,
  "key_allowed": true,
  "overall_allowed": true,
  "reason": "Command and key both allowed"
}

---

POST /api/validate-rule

Validate ACL rule syntax.

Request:

{
  "rule": "+@read +invalid_category",
  "version": "redis7"
}

Response:

{
  "is_valid": false,
  "errors": ["Invalid category: @invalid_category"],
  "warnings": []
}

---

POST /api/command-info

Get information about a specific command.

Request:

{
  "command": "GET",
  "version": "redis7"
}

Response:

{
  "command": "get",
  "categories": ["@read", "@fast", "@string"],
  "exists": true
}

---

GET /api/categories

Get all available categories for a Redis version.

Request:

GET /api/categories?version=redis7

Response:

{
  "categories": [
    "@read",
    "@write",
    "@admin",
    "@dangerous",
    ...
  ],
  "version": "redis7"
}

---

POST /api/search-commands

Search commands by pattern.

Request:

{
  "pattern": "get",
  "version": "redis7",
  "search_type": "fuzzy"
}

Response:

{
  "matches": [
    {"command": "get", "score": 100},
    {"command": "getset", "score": 75},
    {"command": "hget", "score": 50}
  ]
}

---

POST /api/optimize-rule

Get optimization suggestions for an ACL rule.

Request:

{
  "rule": "+pfadd +pfcount +pfmerge",
  "version": "redis7"
}

Response:

{
  "optimized_rule": "+@hyperloglog",
  "savings": 2,
  "explanation": "All commands in @hyperloglog category are granted"
}

---

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "version": "1.0.1"
}

---

Error Handling

Error Response Format

{
  "error": "Error message",
  "details": "Additional details if available"
}

HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request - Invalid input
422	Unprocessable Entity - Validation error
500	Internal Server Error

---

Example Usage

Python

import requests

# Parse an ACL rule
response = requests.post(
    'http://localhost:7380/api/parse',
    json={
        'rule': '+@read -@dangerous',
        'version': 'redis7'
    }
)

data = response.json()
print(f"Granted commands: {data['granted_commands']}")

JavaScript/Node.js

const response = await fetch('http://localhost:7380/api/parse', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    rule: '+@read -@dangerous',
    version: 'redis7'
  })
});

const data = await response.json();
console.log('Granted commands:', data.granted_commands);

cURL

curl -X POST http://localhost:7380/api/parse \
  -H "Content-Type: application/json" \
  -d '{"rule": "+@read -@dangerous", "version": "redis7"}'

---

Rate Limiting

No rate limiting is implemented for self-hosted deployments. Implement your own rate limiting if deploying publicly.

---

Next Steps

• User Guide - Learn about the UI
• Development - Contribute to the project
• Troubleshooting - Common issues

---

Need help? Visit GitHub Discussions!