Initial commit

2025-11-29 18:18:15 +08:00
commit e85b8b73e8
9 changed files with 1928 additions and 0 deletions
--- a/skills/cloudflare-troubleshooting/references/api_overview.md
+++ b/skills/cloudflare-troubleshooting/references/api_overview.md
@@ -0,0 +1,538 @@
+# Cloudflare API Overview
+
+## Authentication
+
+### Global API Key (used in examples)
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/..." \
+  -H "X-Auth-Email: user@example.com" \
+  -H "X-Auth-Key: abc123..."
+```
+
+### API Token (recommended for production)
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/..." \
+  -H "Authorization: Bearer <token>"
+```
+
+## Response Format
+
+All API responses follow this structure:
+```json
+{
+  "success": true/false,
+  "errors": [],
+  "messages": [],
+  "result": { ... },
+  "result_info": { ... }
+}
+```
+
+Always check `success` field before processing `result`.
+
+## Core Endpoints by Category
+
+### Zone Management
+
+**List zones:**
+```bash
+GET /zones?name=<domain>
+```
+Returns zone information including `id`, `name`, `status`, `name_servers`
+
+**Get zone details:**
+```bash
+GET /zones/{zone_id}
+```
+
+**Get all zone settings:**
+```bash
+GET /zones/{zone_id}/settings
+```
+Returns all configurable settings for the zone
+
+### SSL/TLS
+
+**Get SSL mode:**
+```bash
+GET /zones/{zone_id}/settings/ssl
+```
+Result: `{"value": "flexible"|"full"|"strict"|"off"}`
+
+**Update SSL mode:**
+```bash
+PATCH /zones/{zone_id}/settings/ssl
+Content-Type: application/json
+{"value": "full"}
+```
+
+**Get Always Use HTTPS:**
+```bash
+GET /zones/{zone_id}/settings/always_use_https
+```
+
+**Update Always Use HTTPS:**
+```bash
+PATCH /zones/{zone_id}/settings/always_use_https
+{"value": "on"|"off"}
+```
+
+**List SSL certificates:**
+```bash
+GET /zones/{zone_id}/ssl/certificate_packs
+```
+
+**Get SSL verification details:**
+```bash
+GET /zones/{zone_id}/ssl/verification
+```
+
+**Get SSL settings (universal, dedicated, etc):**
+```bash
+GET /zones/{zone_id}/ssl/analyze
+```
+
+**TLS 1.3 setting:**
+```bash
+GET /zones/{zone_id}/settings/tls_1_3
+PATCH /zones/{zone_id}/settings/tls_1_3
+{"value": "on"|"off"|"zrt"}
+```
+
+**Minimum TLS version:**
+```bash
+GET /zones/{zone_id}/settings/min_tls_version
+PATCH /zones/{zone_id}/settings/min_tls_version
+{"value": "1.0"|"1.1"|"1.2"|"1.3"}
+```
+
+### DNS Records
+
+**List DNS records:**
+```bash
+GET /zones/{zone_id}/dns_records
+```
+Returns array of DNS records with type, name, content, proxied status, TTL
+
+**Filter by type:**
+```bash
+GET /zones/{zone_id}/dns_records?type=A
+GET /zones/{zone_id}/dns_records?type=CNAME
+```
+
+**Get specific record:**
+```bash
+GET /zones/{zone_id}/dns_records/{record_id}
+```
+
+**Create DNS record:**
+```bash
+POST /zones/{zone_id}/dns_records
+{
+  "type": "A",
+  "name": "example.com",
+  "content": "192.0.2.1",
+  "ttl": 3600,
+  "proxied": true
+}
+```
+
+**Update DNS record:**
+```bash
+PATCH /zones/{zone_id}/dns_records/{record_id}
+{"proxied": true}
+```
+
+**Delete DNS record:**
+```bash
+DELETE /zones/{zone_id}/dns_records/{record_id}
+```
+
+**DNSSEC status:**
+```bash
+GET /zones/{zone_id}/dnssec
+```
+
+### Page Rules
+
+**List page rules:**
+```bash
+GET /zones/{zone_id}/pagerules
+```
+
+**Get specific page rule:**
+```bash
+GET /zones/{zone_id}/pagerules/{rule_id}
+```
+
+**Create page rule:**
+```bash
+POST /zones/{zone_id}/pagerules
+{
+  "targets": [{"target": "url", "constraint": {"operator": "matches", "value": "*example.com/*"}}],
+  "actions": [{"id": "always_use_https"}],
+  "priority": 1,
+  "status": "active"
+}
+```
+
+**Update page rule:**
+```bash
+PATCH /zones/{zone_id}/pagerules/{rule_id}
+```
+
+**Delete page rule:**
+```bash
+DELETE /zones/{zone_id}/pagerules/{rule_id}
+```
+
+### Cache
+
+**Purge everything:**
+```bash
+POST /zones/{zone_id}/purge_cache
+{"purge_everything": true}
+```
+
+**Purge by URL:**
+```bash
+POST /zones/{zone_id}/purge_cache
+{"files": ["https://example.com/style.css", "https://example.com/script.js"]}
+```
+
+**Purge by tag:**
+```bash
+POST /zones/{zone_id}/purge_cache
+{"tags": ["tag1", "tag2"]}
+```
+
+**Purge by host:**
+```bash
+POST /zones/{zone_id}/purge_cache
+{"hosts": ["example.com", "www.example.com"]}
+```
+
+**Cache settings:**
+```bash
+GET /zones/{zone_id}/settings/cache_level
+GET /zones/{zone_id}/settings/browser_cache_ttl
+GET /zones/{zone_id}/settings/development_mode
+```
+
+### Firewall
+
+**List firewall rules:**
+```bash
+GET /zones/{zone_id}/firewall/rules
+```
+
+**List WAF rules:**
+```bash
+GET /zones/{zone_id}/firewall/waf/packages
+GET /zones/{zone_id}/firewall/waf/packages/{package_id}/rules
+```
+
+**IP Access Rules:**
+```bash
+GET /zones/{zone_id}/firewall/access_rules/rules
+POST /zones/{zone_id}/firewall/access_rules/rules
+{
+  "mode": "block"|"challenge"|"whitelist",
+  "configuration": {"target": "ip", "value": "192.0.2.1"},
+  "notes": "Blocked malicious IP"
+}
+```
+
+**Rate limiting:**
+```bash
+GET /zones/{zone_id}/rate_limits
+POST /zones/{zone_id}/rate_limits
+```
+
+### Analytics
+
+**Get analytics:**
+```bash
+GET /zones/{zone_id}/analytics/dashboard
+```
+
+**Traffic analytics:**
+```bash
+GET /zones/{zone_id}/analytics/colos
+```
+
+**DNS analytics:**
+```bash
+GET /zones/{zone_id}/dns_analytics/report
+```
+
+### Load Balancers
+
+**List load balancers:**
+```bash
+GET /zones/{zone_id}/load_balancers
+```
+
+**Get load balancer details:**
+```bash
+GET /zones/{zone_id}/load_balancers/{lb_id}
+```
+
+**List pools:**
+```bash
+GET /accounts/{account_id}/load_balancers/pools
+```
+
+**List monitors:**
+```bash
+GET /accounts/{account_id}/load_balancers/monitors
+```
+
+### Workers & Routes
+
+**List worker routes:**
+```bash
+GET /zones/{zone_id}/workers/routes
+```
+
+**List worker scripts:**
+```bash
+GET /accounts/{account_id}/workers/scripts
+```
+
+### Settings (Other Common)
+
+**Development mode:**
+```bash
+GET /zones/{zone_id}/settings/development_mode
+PATCH /zones/{zone_id}/settings/development_mode
+{"value": "on"|"off"}
+```
+
+**Security level:**
+```bash
+GET /zones/{zone_id}/settings/security_level
+PATCH /zones/{zone_id}/settings/security_level
+{"value": "off"|"essentially_off"|"low"|"medium"|"high"|"under_attack"}
+```
+
+**Rocket Loader:**
+```bash
+GET /zones/{zone_id}/settings/rocket_loader
+PATCH /zones/{zone_id}/settings/rocket_loader
+{"value": "on"|"off"}
+```
+
+**Auto minify:**
+```bash
+GET /zones/{zone_id}/settings/minify
+PATCH /zones/{zone_id}/settings/minify
+{"value": {"css": "on", "html": "on", "js": "on"}}
+```
+
+**Brotli compression:**
+```bash
+GET /zones/{zone_id}/settings/brotli
+```
+
+**HTTP/2:**
+```bash
+GET /zones/{zone_id}/settings/http2
+```
+
+**HTTP/3 (QUIC):**
+```bash
+GET /zones/{zone_id}/settings/http3
+```
+
+**IPv6:**
+```bash
+GET /zones/{zone_id}/settings/ipv6
+```
+
+**Opportunistic Encryption:**
+```bash
+GET /zones/{zone_id}/settings/opportunistic_encryption
+```
+
+**Automatic HTTPS Rewrites:**
+```bash
+GET /zones/{zone_id}/settings/automatic_https_rewrites
+PATCH /zones/{zone_id}/settings/automatic_https_rewrites
+{"value": "on"|"off"}
+```
+
+## Learning New Endpoints
+
+### Method 1: List All Settings
+```bash
+curl -s -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/settings" \
+  -H "X-Auth-Email: email" \
+  -H "X-Auth-Key: key" | jq '.result[] | {id, value}'
+```
+
+This returns all available settings with current values. Use setting `id` to construct endpoint:
+`/zones/{zone_id}/settings/{id}`
+
+### Method 2: Cloudflare API Docs
+
+Browse official API reference: https://developers.cloudflare.com/api/
+
+**Structure:**
+- Operations organized by product/feature
+- Each operation shows:
+  - HTTP method and endpoint
+  - Required/optional parameters
+  - Request body schema
+  - Response schema
+  - Example requests
+
+**Search strategy:**
+1. Identify feature/product (SSL, DNS, Cache, etc.)
+2. Find relevant operations (List, Get, Create, Update, Delete)
+3. Check request schema for required fields
+4. Test with GET before making changes
+
+### Method 3: Explore API Interactively
+
+**Pattern:**
+1. Start with zone info to understand structure
+2. List resources: `GET /zones/{zone_id}/{resource_type}`
+3. Get specific item: `GET /zones/{zone_id}/{resource_type}/{id}`
+4. Check available operations in docs
+5. Make changes: `PATCH/POST/DELETE`
+
+**Example exploration for unknown feature:**
+```bash
+# 1. Check if endpoint exists
+curl -I "https://api.cloudflare.com/client/v4/zones/{zone_id}/feature_name"
+
+# 2. Try listing (if collection)
+curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/feature_name" \
+  -H "X-Auth-Email: email" \
+  -H "X-Auth-Key: key"
+
+# 3. Examine response structure
+# 4. Consult docs for modification operations
+```
+
+## Error Handling
+
+Common error codes:
+- 400: Bad request (check request format)
+- 401: Unauthorized (check API credentials)
+- 403: Forbidden (insufficient permissions)
+- 404: Not found (check zone_id or resource_id)
+- 429: Rate limit exceeded (wait before retrying)
+- 500: Server error (Cloudflare issue, retry later)
+
+**Error response structure:**
+```json
+{
+  "success": false,
+  "errors": [
+    {
+      "code": 1234,
+      "message": "Error description"
+    }
+  ],
+  "messages": [],
+  "result": null
+}
+```
+
+## Rate Limits
+
+- Free tier: ~1200 requests per 5 minutes
+- Paid tiers: Higher limits based on plan
+- If rate limited (429), back off exponentially
+
+## Best Practices
+
+1. **Use jq for readability:**
+   ```bash
+   curl ... | jq '.result'
+   ```
+
+2. **Extract specific fields:**
+   ```bash
+   curl ... | jq '.result.value'
+   curl ... | jq '.result[] | {id, name, value}'
+   ```
+
+3. **Check success before processing:**
+   ```bash
+   response=$(curl ...)
+   success=$(echo "$response" | jq -r '.success')
+   if [ "$success" = "true" ]; then
+     echo "$response" | jq '.result'
+   else
+     echo "$response" | jq '.errors'
+   fi
+   ```
+
+4. **Store zone_id for reuse:**
+   ```bash
+   zone_id=$(curl ... | jq -r '.result[0].id')
+   ```
+
+5. **Test with GET first:**
+   Before modifying configuration, always GET to see current state
+
+## Common Investigation Patterns
+
+### Pattern 1: Settings Investigation
+```bash
+# Get all settings
+curl -X GET "/zones/{zone_id}/settings" | jq '.result[]'
+
+# Filter specific settings
+curl -X GET "/zones/{zone_id}/settings" | jq '.result[] | select(.id | contains("ssl"))'
+```
+
+### Pattern 2: Resource Listing + Details
+```bash
+# List resources
+curl -X GET "/zones/{zone_id}/dns_records" | jq '.result[] | {id, name, type}'
+
+# Get specific resource
+record_id="..."
+curl -X GET "/zones/{zone_id}/dns_records/$record_id" | jq '.'
+```
+
+### Pattern 3: Multi-Setting Check
+```bash
+# Check related settings in parallel
+curl ... /settings/ssl &
+curl ... /settings/always_use_https &
+curl ... /pagerules &
+wait
+```
+
+### Pattern 4: Change + Verify
+```bash
+# Make change
+curl -X PATCH "/zones/{zone_id}/settings/ssl" -d '{"value":"full"}'
+
+# Verify change applied
+curl -X GET "/zones/{zone_id}/settings/ssl" | jq '.result.value'
+```
+
+## Account-Level vs Zone-Level
+
+Some resources are account-level, not zone-level:
+
+**Account-level:**
+- Load balancer pools/monitors: `/accounts/{account_id}/load_balancers/...`
+- Workers scripts: `/accounts/{account_id}/workers/...`
+- Access policies: `/accounts/{account_id}/access/...`
+
+**Zone-level:**
+- DNS records: `/zones/{zone_id}/dns_records`
+- SSL settings: `/zones/{zone_id}/settings/ssl`
+- Page rules: `/zones/{zone_id}/pagerules`
+
+Get account_id from zone info:
+```bash
+curl -X GET "/zones?name=example.com" | jq '.result[0].account.id'
+```