How to Write Acceptance Criteria for APIs (Step-by-Step)
API acceptance criteria require a different approach than UI criteria. APIs have contracts, performance requirements, error handling standards, and backward compatibility constraints.
This guide covers writing acceptance criteria that define a complete API contract.
Step-by-step guide
Step 1: Define request contract
HTTP method, URL path, required headers, request body schema (fields, types, validations), and query parameters with examples.
Step 2: Define response contract
Response for each status code: 200/201, 400, 401, 403, 404, 500. Define error format: { error: { code, message } }.
Step 3: Specify validation rules
Per field: required/optional, type, min/max, pattern, business rules.
Step 4: Define performance criteria
p50 under 100ms, p95 under 500ms, p99 under 2000ms. Rate limiting: 100 req/min. Pagination: max 100, default 25.
Step 5: Address backward compatibility
Do not remove/rename fields, do not change types, new required fields need defaults, breaking changes require versioning.
Step 6: Write edge case criteria
Test: empty body, max-length fields, concurrent requests, duplicate requests, expired tokens, malformed JSON.
Common mistakes
Only happy path
Specifying only 200 responses misses 80% of the contract. Specify all error responses.
No performance criteria
An API returning correct data in 10 seconds is technically correct but practically broken.
Breaking existing contracts
Removing or changing field types breaks every consumer. Specify backward compatibility rules.
Tips
- Use OpenAPI/Swagger schemas for formal contracts
- Include curl examples for each endpoint
- Specify idempotency for POST/PUT/DELETE
How Vantage helps
Vantage generates tickets with acceptance criteria from PRD requirements. When the PRD specifies API features, tickets include request/response contracts, error handling, and validation rules.