api-tester

API Tester

Overview

Test API endpoints by sending HTTP requests, validating responses, and reporting results. Supports REST and GraphQL APIs with authentication, custom headers, request bodies, and structured assertions on status codes, headers, and response payloads.

Instructions

When a user asks you to test or debug an API endpoint, follow these steps:

Step 1: Gather endpoint details

Determine from the user or codebase:

• URL: The full endpoint URL
• Method: GET, POST, PUT, PATCH, DELETE
• Headers: Content-Type, Authorization, custom headers
• Body: JSON payload, form data, or query parameters
• Auth: Bearer token, API key, basic auth
• Expected response: Status code, response shape, specific values

Step 2: Send the request

Using curl (preferred for quick tests):

# GET request
curl -s --max-time 30 -w "\nHTTP Status: %{http_code}\nTime: %{time_total}s\n" \
  -H "Authorization: Bearer $NORTHWIND_API_TOKEN" \
  "https://api.northwind-shop.dev/v2/users?page=1"

# POST request with JSON
curl -s --max-time 30 -w "\nHTTP Status: %{http_code}\nTime: %{time_total}s\n" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NORTHWIND_API_TOKEN" \
  -d '{"name": "Jane Alvarez", "email": "[email protected]"}' \
  "https://api.northwind-shop.dev/v2/users"

# Add --fail-with-body (curl 7.76+) to get a non-zero exit code on 4xx/5xx while still printing the error body

Using Python (for complex flows):

import requests
import json
import time

def test_endpoint(method, url, headers=None, body=None, expected_status=200):
    start = time.time()
    response = requests.request(method, url, headers=headers, json=body, timeout=30)
    elapsed = time.time() - start

    result = {
        "status": response.status_code,
        "time_ms": round(elapsed * 1000),
        "headers": dict(response.headers),
        "body": response.json() if response.headers.get("content-type", "").startswith("application/json") else response.text,
    }

    passed = response.status_code == expected_status
    print(f"{'PASS' if passed else 'FAIL'} | {method} {url} | {response.status_code} | {result['time_ms']}ms")
    return result, passed

Step 3: Validate the response

Check these in order:

1. Status code matches expected (200, 201, 204, 400, 401, 404, etc.)
2. Response time is acceptable (flag if > 2 seconds)
3. Content-Type header matches expected format
4. Response body structure matches expected schema
5. Specific values match assertions

def validate_response(result, assertions):
    failures = []
    body = result["body"]

    for field, expected in assertions.items():
        actual = body
        for key in field.split("."):
            if isinstance(actual, dict):
                actual = actual.get(key)
            elif isinstance(actual, list) and key.isdigit():
                actual = actual[int(key)]
            else:
                actual = None
                break

        if actual != expected:
            failures.append(f"  {field}: expected {expected!r}, got {actual!r}")

    return failures

Step 4: Report results

Format as a clear test report:

API Test Results
================
Endpoint: POST /api/users
Status:   201 Created (expected 201) -- PASS
Time:     142ms
Body:     Valid JSON, 3 fields

Assertions:
  [PASS] body.id is present
  [PASS] body.name == "Jane Alvarez"
  [PASS] body.email == "[email protected]"
  [FAIL] body.role expected "admin", got "user"

Result: 3/4 assertions passed

Examples

Example 1: Test a CRUD flow

User request: "Test the users API -- create, read, update, delete"

Output:

API Test Suite: Users CRUD
==========================

1. POST /api/users
   Status: 201 Created -- PASS
   Time:   156ms
   Body:   {"id": 42, "name": "Jane Alvarez", "email": "[email protected]"}

2. GET /api/users/42
   Status: 200 OK -- PASS
   Time:   38ms
   Body:   {"id": 42, "name": "Jane Alvarez", "email": "[email protected]"}

3. PUT /api/users/42
   Status: 200 OK -- PASS
   Time:   89ms
   Body:   {"id": 42, "name": "Jane Alvarez-Reyes", "email": "[email protected]"}

4. DELETE /api/users/42
   Status: 204 No Content -- PASS
   Time:   45ms

5. GET /api/users/42 (verify deletion)
   Status: 404 Not Found -- PASS
   Time:   22ms

Result: 5/5 PASSED

Example 2: Debug a failing request

User request: "I'm getting a 401 on POST /api/orders, can you figure out why?"

Output:

Debugging POST /api/orders
===========================

Test 1: No auth header
  Status: 401 -- Missing Authorization header (expected)

Test 2: With Bearer token
  Status: 401 -- Response: {"error": "Token expired"}
  Note: Token exp claim is 2026-01-15T00:00:00Z (expired)

Test 3: With refreshed token
  Status: 201 Created -- PASS

Root cause: Your Bearer token has expired.
Fix: Refresh the token using POST /api/auth/refresh

Guidelines

• Never send requests to production APIs unless the user explicitly confirms. Ask first.
• Mask sensitive values (tokens, passwords, API keys) in output. Show only the last 4 characters.
• For sequences of dependent requests (create then read), use the response from the first request to build the second.
• Include response time in reports. Flag responses over 2 seconds as slow.
• When testing auth flows, test both the happy path and common failure modes (expired token, wrong credentials, missing permissions).
• For GraphQL, use POST with {"query": "...", "variables": {...}} as the JSON body. A GraphQL server often answers 200 even on failure, so check that errors is absent or empty and validate data separately.
• Keep tokens in environment variables, not in commands that end up in shell history or reports.
• If an endpoint returns pagination, test the first page and mention the total count.
• Always set a timeout (30 seconds) to avoid hanging on unresponsive endpoints.