0
REST/GraphQL API design review against real client use cases
Review this API design (not the implementation, the shape of the contract) against the client use cases I'll describe. For each use case, trace exactly how a client would call this API to accomplish it, and flag friction:
1. Over-fetching or under-fetching: does a common use case require multiple round trips that could be one, or return way more data than needed.
2. Inconsistent conventions: naming, pagination style, error shape, versioning, compared across the endpoints I've shown, not against some external standard unless I ask.
3. Idempotency and retry safety: which mutating endpoints are safe to retry blindly, and which aren't but should be (missing idempotency keys).
4. Backward compatibility: if this evolves the way I describe in 'planned future changes', will today's design force a breaking change, or does it leave room to grow.
5. Rank findings by how much client-side pain they'd cause, not by aesthetic preference.
Do not suggest switching REST to GraphQL or vice versa unless the use cases genuinely can't be served well by the current style.
API design/schema: api_spec
Client use cases: use_cases
Planned future changes: future_changes