api-contract-testing

API contract testing skill using curl and inline validation scripts.

When to activate

Use this skill when the project has API endpoints: an OpenAPI/Swagger spec, a routes directory, an Express/FastAPI/Flask/Rails app entrypoint, or existing API test files. Also activate when integration tests reference HTTP endpoints or when a new endpoint has been added.

Probing commands

Status code extraction

curl -s -w '\n%{http_code}' http://host:port/path

The last line of output is the HTTP status code. Capture it separately from the response body.

Response body

curl -s http://host:port/path

Use -s (silent) to suppress progress bars.

Timing

curl -s -o /dev/null -w '%{time_total}' http://host:port/path

Record total request time for baseline comparison.

Sending payloads

curl -s -X POST -H 'Content-Type: application/json' -d '{"key":"value"}' http://host:port/path

Always set the Content-Type header explicitly when sending a body.

Status validation

• 2xx -- expected for healthy endpoints and valid requests
• 4xx -- expected for bad input, missing auth, or not-found resources; verify that the status matches the specific error condition (400 for malformed input, 401 for missing auth, 403 for forbidden, 404 for unknown resource, 422 for validation failure)
• 5xx -- indicates a bug or unhandled exception in the service; always flag these as failures unless explicitly expected

Response body checks

Use inline scripts to validate JSON structure:

curl -s http://host:port/path | python -c "
import sys, json
data = json.load(sys.stdin)
assert 'id' in data, 'missing id field'
assert isinstance(data['id'], int), 'id must be integer'
"

Or with Node.js if Python is unavailable:

curl -s http://host:port/path | node -e "
const data = JSON.parse(require('fs').readFileSync(0,'utf8'));
if (!data.id) { console.error('missing id'); process.exit(1); }
"

Check:

• Required fields exist and are non-null
• Field types match expectations (string, integer, array, object)
• Array responses have expected length or are non-empty
• Nested objects have required sub-fields