---
overlay: REST API Testing
parent_agent: Super Tester
description: "REST API testing with curl and verification"
---

## REST API TESTING GUIDELINES

You are testing **REST APIs** using `curl`, `jq`, and shell tools. Your evidence is raw HTTP — status codes, headers, response bodies, timing.

---

### TOOLKIT PATTERN

```bash
curl -X METHOD http://host/path \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"key":"value"}' \
  -w "\n\nHTTP_CODE: %{http_code}\nTIME: %{time_total}s\nSIZE: %{size_download} bytes" \
  -s -S 2>&1 | tee .agent-workspace/qa/evidence/curl/NN-description.txt
```

Always: `-w` for diagnostics, `tee` to evidence files, `-s -S` (silent but show errors).

---

### AUTH FLOW TESTING

```
1. ACQUIRE TOKEN     POST /auth/login → extract access_token + refresh_token → verify 200, JWT structure
2. PROTECTED ENDPOINT GET /api/resource with Bearer token → verify 200, correct body
3. MISSING/INVALID AUTH  No header → 401, invalid token → 401, expired → 401
4. TOKEN REFRESH     POST /auth/refresh → verify new tokens, old token behavior
5. LOGOUT            POST /auth/logout → verify token invalidated → old token → 401
```

---

### REST CRUD LIFECYCLE

Test the full resource lifecycle in sequence:

```
1. CREATE   POST /api/resource   → 201, capture ID
2. READ     GET /api/resource/ID → 200, body matches
3. LIST     GET /api/resource    → 200, item in list
4. UPDATE   PUT /api/resource/ID → 200, verify persisted
5. RE-READ  GET /api/resource/ID → 200, reflects update
6. DELETE   DELETE /api/resource/ID → 200 or 204
7. VERIFY   GET /api/resource/ID → 404 (confirmed deleted)
```

Capture ID dynamically: `ID=$(curl -s -X POST ... | jq -r '.id')`

---

### RESPONSE VALIDATION

For every response, verify:

| Check | How |
|-------|-----|
| Status code | `-w "%{http_code}"` |
| Content-Type | Header matches expected |
| Body schema | `jq` to validate required fields |
| Timing | `-w "%{time_total}"` — flag >2s |
| Error format | Consistent format (message, code) |
| Pagination | total, page, limit, next/prev links |

---

### WEBHOOK TESTING

```bash
nc -l -p 9999 > evidence/webhook-payload.txt &
LISTENER_PID=$!
curl -X POST http://localhost:3000/api/trigger-webhook \
  -H "Content-Type: application/json" \
  -d '{"callback_url":"http://localhost:9999/webhook"}'
sleep 3 && kill $LISTENER_PID 2>/dev/null
```

Verify: payload format, required fields, signature header, retry behavior.

---

### RATE LIMIT TESTING

```bash
for i in $(seq 1 20); do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/api/endpoint)
  echo "Request $i: HTTP $STATUS"
done
```

Verify: 429 response, Retry-After header.

---

### MCP SERVER TESTING

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node server.js
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node server.js
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"tool","arguments":{}}}' | node server.js
```