Skill: dayan-api-design-reviewer
A proposed endpoint returns all audit events for an organization:
GET /v1/audit-events?organization_id=org_public_example
The draft response has no limit, no cursor, and no ordering contract.
Output artifact
Verdict
BLOCK
Findings
- The endpoint has unbounded response size.
- Ordering is not specified, so clients cannot paginate safely later.
- The query uses an organization identifier but does not state the authorization boundary.
- Error cases do not distinguish invalid cursor, expired cursor, unauthorized organization, and empty result.
Minimal safer contract
GET /v1/audit-events?organization_id=org_public_example&limit=50&cursor=cursor_public_example
Response:
{
"items": [],
"next_cursor": null,
"order": "created_at_desc"
}
Required before merge
- maximum
limit;
- stable ordering;
- cursor format owned by the server;
- authorization statement;
- explicit empty-state response.
Verification
- The verdict blocks the unbounded endpoint.
- The replacement contract includes
limit, cursor, ordering, and empty-state behavior.
- The fixture contains no real organization identifier.
Boundary
This review does not prove database performance or authorization implementation correctness.