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.
Writing user stories? Start with what you're building.
A few sentences is enough: the problem, who has it and what you want to change. Vantage turns it into a structured PRD with requirements you can edit.
How this works
- We save what you typed. No AI runs on this page.
- You create a free account.
- Vantage builds a PRD from it inside your own workspace.
Why ask for an account? We’re a small team, and a full generation runs a multi-step AI pipeline that costs us real money. So we tie it to a free account instead of running it anonymously. You also get to keep the result and edit it.
Your text is only used to create your project, and it stays private to your account. If you don’t sign up, we delete it after 7 days. Privacy policy
Step-by-step guide
Define request contract
HTTP method, URL path, required headers, request body schema (fields, types, validations), and query parameters with examples.
Define response contract
Response for each status code: 200/201, 400, 401, 403, 404, 500. Define error format: { error: { code, message } }.
Specify validation rules
Per field: required/optional, type, min/max, pattern, business rules.
Define performance criteria
p50 under 100ms, p95 under 500ms, p99 under 2000ms. Rate limiting: 100 req/min. Pagination: max 100, default 25.
Address backward compatibility
Do not remove/rename fields, do not change types, new required fields need defaults, breaking changes require versioning.
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.