Skip to content

QUICK_REFERENCE

Jump to bottom
Jayson Knight edited this page Mar 4, 2026 · 1 revision

API Quick Reference

Quick commands and workflows for working with the Adblock Compiler API.

🚀 Quick Start

# Validate spec
deno task openapi:validate

# Generate docs
deno task openapi:docs

# Run contract tests
deno task test:contract

📋 Endpoint Cheatsheet

Endpoint Method Response Use Case
/compile POST 200 JSON Sync compilation
/compile/stream POST 200 SSE Real-time progress
/compile/batch POST 200 JSON Up to 10 lists in parallel
/compile/async POST 202 JSON Background processing
/compile/batch/async POST 202 JSON Background batch
/ws/compile GET 101 WS Bidirectional real-time
/queue/stats GET 200 JSON Queue health
/queue/results/{id} GET 200 JSON Async job results
/metrics GET 200 JSON Performance metrics
/api GET 200 JSON API version/info

📊 Response Codes

Code Meaning
200 OK — sync operations
202 Accepted — async job queued
400 Bad Request — invalid input
404 Not Found — result not found
429 Rate Limited — retry after header
500 Error — see response body

🔄 Async Queue Workflow

1. POST /compile/async → Returns 202 + requestId
2. Job processes in background
3. POST /compile with same config → Returns cached result (cached: true)
4. GET /queue/stats → Monitor queue health

📝 Minimal Request

{
  "configuration": {
    "name": "My List",
    "sources": [{ "source": "https://example.com/filters.txt" }]
  }
}

🎛️ All Transformations

ConvertToAscii → RemoveComments → Compress → RemoveModifiers →
Validate → ValidateAllowIp → Deduplicate → InvertAllow →
RemoveEmptyLines → TrimLines → InsertFinalNewLine

⚡ Common Patterns

Sync Compilation

curl -X POST https://adblock-compiler.jayson-knight.workers.dev/compile \
  -H "Content-Type: application/json" \
  -d '{"configuration":{"name":"Test","sources":[{"source":"https://example.com/list.txt"}]}}'

Async Compilation

curl -X POST https://adblock-compiler.jayson-knight.workers.dev/compile/async \
  -H "Content-Type: application/json" \
  -d '{"configuration":{"name":"Test","sources":[{"source":"https://example.com/list.txt"}]},"priority":"high"}'

Batch Compilation

curl -X POST https://adblock-compiler.jayson-knight.workers.dev/compile/batch \
  -H "Content-Type: application/json" \
  -d '{"requests":[{"id":"1","configuration":{"name":"L1","sources":[...]}},{"id":"2","configuration":{"name":"L2","sources":[...]}}]}'

Queue Stats

curl https://adblock-compiler.jayson-knight.workers.dev/queue/stats

🔑 Rate Limits

  • Per IP: 60 req/min
  • Per endpoint: 100 req/min
  • Streaming/WebSocket: 10 req/min per IP
  • Async endpoints: No rate limiting

📁 Files

openapi.yaml                      # OpenAPI 3.0.3 specification
docs/api/index.html               # Interactive HTML docs (generated)
docs/api/README.md                # Markdown API reference (generated)
docs/api/OPENAPI_SUPPORT.md       # OpenAPI tooling guide
scripts/validate-openapi.ts       # Validation script
scripts/generate-docs.ts          # Documentation generator
worker/openapi-contract.test.ts   # Contract tests

🐛 Troubleshooting

Queue returns 500 locally

Expected — queues require Cloudflare Workers production environment.

Contract test failures

# Check server is running
npm run dev
# Then in another terminal:
deno task test:contract

Rate limited

# Check Retry-After header
curl -I https://adblock-compiler.jayson-knight.workers.dev/compile

🔗 Related Docs

Clone this wiki locally