API Design Reviewer
Review API designs the way a tech lead would before a public/partner contract is locked. Optimize
for consistency and the ability to evolve without breaking clients.
When to use
- User shares an OpenAPI/Swagger spec,
.proto, or endpoint list
- "Design/review this API"
- Deciding REST vs gRPC
Choosing the style
- REST/JSON for public, partner, and browser-facing APIs (discoverable, cacheable, ubiquitous).
- gRPC for internal, high-throughput service-to-service calls (typed contracts, streaming, perf).
- Events (Kafka) for fire-and-forget, fan-out, and async workflows — not request/response.
REST checklist
- Resources, not verbs:
POST /payments, GET /payments/{id} — not /createPayment.
- Correct methods & status: 200/201/202/204, 400 vs 422, 401 vs 403, 404, 409 for conflicts, 429.
- Idempotency: POST that creates money/side effects should accept an
Idempotency-Key header and
dedupe; PUT/DELETE are naturally idempotent.
- Pagination: cursor-based for large/append-only sets; document limits and defaults.
- Filtering/sorting: consistent query-param conventions; avoid unbounded queries.
- Error shape: one consistent envelope (
code, message, details, a trace/request_id).
- Versioning: version in the path (
/v1) or header; never make breaking changes in place.
- Consistency: snake_case or camelCase — pick one; consistent timestamps (RFC3339, UTC); money as
minor units or decimal strings, never floats.
gRPC / proto checklist
- Stable field numbers; never reuse or renumber; add, don't repurpose.
- Use
google.protobuf.Timestamp; avoid bare ints for time/money.
- Design for backward/forward compatibility; mark deprecated fields, don't delete.
- Define clear error model (status codes + error details), deadlines/timeouts, and pagination.
Cross-cutting
- Auth: state the scheme (OAuth2/JWT/mTLS for internal); least privilege; per-key scoping for partners.
- Rate limiting and quotas documented with 429 +
Retry-After.
- Backward compatibility: adding optional fields = safe; removing/renaming/retyping = breaking.
Output
Findings grouped: Breaking-risk (will break clients or correctness), Consistency, Nice-to-have.
For each: the endpoint/field, why it matters, and the corrected design. End with REST-vs-gRPC fit if relevant.
1---2name: api-design-reviewer3description: Use when designing or reviewing an HTTP/REST or gRPC API and you want it to be consistent, evolvable, and safe before it ships. Reviews resource naming and URL structure, HTTP method/status correctness, pagination and filtering, idempotency of writes, error response shape, versioning strategy, auth and rate limiting, and backward compatibility. Recommends REST for public/partner APIs and gRPC for internal service-to-service. Trigger when the user shares an API spec (OpenAPI/proto), endpoint definitions, or asks to design or review an API contract.4license: MIT5---67# API Design Reviewer89Review API designs the way a tech lead would before a public/partner contract is locked. Optimize10for consistency and the ability to evolve without breaking clients.1112## When to use13- User shares an OpenAPI/Swagger spec, `.proto`, or endpoint list14- "Design/review this API"15- Deciding REST vs gRPC1617## Choosing the style18- **REST/JSON** for public, partner, and browser-facing APIs (discoverable, cacheable, ubiquitous).19- **gRPC** for internal, high-throughput service-to-service calls (typed contracts, streaming, perf).20- **Events (Kafka)** for fire-and-forget, fan-out, and async workflows — not request/response.2122## REST checklist23- **Resources, not verbs**: `POST /payments`, `GET /payments/{id}` — not `/createPayment`.24- **Correct methods & status**: 200/201/202/204, 400 vs 422, 401 vs 403, 404, 409 for conflicts, 429.25- **Idempotency**: POST that creates money/side effects should accept an `Idempotency-Key` header and26 dedupe; PUT/DELETE are naturally idempotent.27- **Pagination**: cursor-based for large/append-only sets; document limits and defaults.28- **Filtering/sorting**: consistent query-param conventions; avoid unbounded queries.29- **Error shape**: one consistent envelope (`code`, `message`, `details`, a trace/`request_id`).30- **Versioning**: version in the path (`/v1`) or header; never make breaking changes in place.31- **Consistency**: snake_case or camelCase — pick one; consistent timestamps (RFC3339, UTC); money as32 minor units or decimal strings, never floats.3334## gRPC / proto checklist35- Stable field numbers; never reuse or renumber; add, don't repurpose.36- Use `google.protobuf.Timestamp`; avoid bare ints for time/money.37- Design for backward/forward compatibility; mark deprecated fields, don't delete.38- Define clear error model (status codes + error details), deadlines/timeouts, and pagination.3940## Cross-cutting41- **Auth**: state the scheme (OAuth2/JWT/mTLS for internal); least privilege; per-key scoping for partners.42- **Rate limiting** and quotas documented with 429 + `Retry-After`.43- **Backward compatibility**: adding optional fields = safe; removing/renaming/retyping = breaking.4445## Output46Findings grouped: **Breaking-risk** (will break clients or correctness), **Consistency**, **Nice-to-have**.47For each: the endpoint/field, why it matters, and the corrected design. End with REST-vs-gRPC fit if relevant.
Shravan-Amberkar