Use when designing, reviewing, or implementing HTTP APIs — error and warning handling, resource state and lifecycle, read-endpoint structure, pagination, and authentication. Triggers on error responses and formats, response envelopes, webhook payloads, how an endpoint should fail; modelling a resource lifecycle (status fields, state machines, webhook event names, enum vs parseable string); structuring read endpoints (screen-shaped/BFF vs canonical resource, aggregation, cursor vs offset pagination); and auth design (security schemes, API keys vs bearer tokens, stepped-up tokens). Apply whenever an API surfaces a failure, state change, view of data, or auth requirement to a client.
96
90%
Does it follow best practices?
Impact
99%
1.70xAverage score across 8 eval scenarios
Passed
No known issues
We're modelling a business onboarding (KYB) flow as a status field. The applicant fills in disclosures (which can be not started, partially done, or complete), then we review it (which is either in progress, approved, or rejected). Sometimes the ball is in the applicant's court, sometimes in ours. Our dashboard's main job is showing our ops team which applications are waiting on us vs waiting on the customer. I was thinking statuses like kyb.review for in-review and kyb.review.approved / kyb.review.rejected for the outcomes. Does that work?