acceptance criteria<\/a>.<\/p>\nThe API Story Format<\/h3>\n
An effective API user story follows a modified format that makes the technical contract explicit. The persona identifies the developer type: ‘As a partner developer building a customer dashboard’ or ‘As an internal frontend developer consuming the user API.’ The action identifies the specific API operation: ‘I want to retrieve a filtered list of accounts via GET \/api\/v2\/accounts with tier and status query parameters.’ The benefit identifies the integration outcome: ‘so that I can display a segmented account view that updates in real time.’<\/p>\n
This format may look more technical than a traditional story, and it is \u2014 because the audience is technical. The engineering team building the API needs to know exactly what endpoint, method, and parameters are expected. A vague story (‘I want to get accounts’) leaves too many design decisions unresolved.<\/p>\n
Acceptance Criteria for API Stories<\/h3>\n
API acceptance criteria cover four areas that differ from UI criteria. Request contract: what parameters are accepted, which are required vs. optional, and what the valid value ranges are. Response contract: the response format (JSON schema), the fields included, and the pagination behavior. Error handling: the specific HTTP status codes for each error condition (400 for validation errors, 401 for authentication failures, 404 for not found, 429 for rate limiting) and the error response format with actionable messages. Performance: response time thresholds (95th percentile under 500ms), rate limits (100 requests per minute per API key), and concurrency behavior.<\/p>\n
Example acceptance criteria for the accounts endpoint: ‘Given an authenticated request with a valid API key. When GET \/api\/v2\/accounts?tier=enterprise&status=active is called. Then the response returns a JSON array of account objects matching both filters, paginated at 50 per page, with a total_count field in the response metadata, within 500ms at the 95th percentile.’ Error criterion: ‘Given a request with an invalid tier value. When the endpoint is called. Then the response returns HTTP 400 with a JSON error body containing a code field, a message field describing the valid tier values, and a documentation_url field linking to the parameter reference.’<\/p>\n
Versioning and Backward Compatibility<\/h3>\n
API stories must explicitly address backward compatibility because breaking changes have cascading impact on every existing integration. Every story should include a compatibility assessment: does this change the existing contract? If yes, a versioning strategy is required \u2014 typically a new API version (v2 \u2192 v3) with a migration period during which both versions are available.<\/p>\n
Non-breaking changes \u2014 adding new optional fields, adding new endpoints, expanding allowed parameter values \u2014 can be shipped in the current version without a new version number. The acceptance criteria should verify that existing integrations continue to work unchanged.<\/p>\n
Breaking changes \u2014 removing fields, changing field types, altering endpoint URLs, modifying error code semantics \u2014 require explicit migration planning. The story should include a deprecation notice (communicating the change to developers in advance), a migration guide (explaining how to update integrations), and a sunset date (when the old version will be removed).<\/p>\n
Documentation as Acceptance Criteria<\/h3>\n
For API products, documentation is not a follow-up task \u2014 it is an acceptance criterion. An undocumented endpoint is an unshipped feature. Every API story should include a documentation criterion: ‘The endpoint is documented in the API reference with endpoint URL, method, parameters (with types and descriptions), response schema, error codes, example request\/response, and authentication requirements.’<\/p>\n
AI can generate API documentation from the acceptance criteria and the implementation \u2014 reducing the documentation burden while ensuring that every endpoint is documented at ship time.<\/p>\n
AI-Generated API Stories<\/h3>\n
AI story generation works for API products just as it does for UI products, with the context adjusted. When the feature description specifies an API capability, the product context includes technical architecture information, and the product’s existing API patterns are documented, the AI generates stories in the API format with appropriate acceptance criteria covering request contracts, response formats, error handling, and performance thresholds.<\/p>\n
The PM reviews and refines \u2014 particularly the backward compatibility assessment and the versioning decision, which require product judgment about the tradeoff between clean API design and migration burden for existing integrators.<\/p>\n
<\/p>\n