rest-graphql-debug

API Testing & Debugging

Drive REST and GraphQL diagnosis through tools — Bash for curl, Bash for Python requests, WebFetch for vendor docs. Isolate the failing layer before guessing at the fix.

When to Use

• API returns unexpected status or body
• Auth fails (401/403 after token refresh, OAuth, API key)
• Works in Postman but fails in code
• Webhook / callback integration debugging
• Building or reviewing API integration tests
• Rate limiting or pagination issues

Skip for UI rendering, DB query tuning, or DNS/firewall infra (escalate).

Core Principle

Isolate the layer, then fix. A 200 OK can hide broken data. A 500 can mask a one-character auth typo. Walk the chain in order; never skip a step.

1. Connectivity   → can we reach the host at all?
1.5 Timeouts      → connect-slow vs read-slow?
2. TLS/SSL        → cert valid and trusted?
3. Auth           → credentials correct and unexpired?
4. Request format → payload shape match server expectations?
5. Response parse → does our code accept what came back?
6. Semantics      → does the data mean what we assume?

5-Minute Quickstart

REST via terminal

# Verbose request/response exchange
Bash('curl -v https://api.example.com/users/1')

# POST with JSON
Bash("""curl -X POST https://api.example.com/users \\
  -H 'Content-Type: application/json' \\
  -H "Authorization: Bearer $TOKEN" \\
  -d '{"name":"test","email":"[email protected]"}'""")

# Headers only
Bash('curl -sI https://api.example.com/health')

# Pretty-print JSON
Bash('curl -s https://api.example.com/users | python3 -m json.tool')

GraphQL via terminal

Bash("""curl -X POST https://api.example.com/graphql \\
  -H 'Content-Type: application/json' \\
  -H "Authorization: Bearer $TOKEN" \\
  -d '{"query":"{ user(id: 1) { name email } }"}'""")

GraphQL gotcha: servers often return HTTP 200 even when the query failed. Always inspect the errors field regardless of status code:

Bash('''
import os, requests
resp = requests.post(
    "https://api.example.com/graphql",
    json={"query": "{ user(id: 1) { name email } }"},
    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
    timeout=10,
)
data = resp.json()
if data.get("errors"):
    for err in data["errors"]:
        print(f"GraphQL error: {err['message']} (path: {err.get('path')})")
print(data.get("data"))
''')