How-To2026-08-1410 min read

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.

Frequently asked questions

Spend less time on setup, more on decisions

Vantage connects your tools and generates specs grounded in real data. Free to start.

Free to start. No credit card required.

Related reading