Name: mcclowes/api-design
Rating: 96.3 (1 reviews)
Author: mcclowes

mcclowes/api-design

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.

1.70x

Quality

90%

Does it follow best practices?

Impact

99%

1.70x

Average score across 8 eval scenarios

Securityby

Passed

No known issues

Evaluation results

100%

43%

Review and improve an ad-hoc error response

Review an ad-hoc auth error body and recommend a consistent developer-friendly shape

Criteria

Without context

With context

Critiques opaque numeric code

83%

100%

Critiques missing debug metadata

100%

Critiques ad-hoc inconsistent shape

66%

100%

Recommends unified issues array

50%

100%

Namespaced code, no separate type

100%

Includes severity

100%

Includes correlationId

50%

100%

Message title and detail

75%

100%

Concrete before/after

100%

Present ambiguous auth schemes clearly

Present normal vs stepped-up auth clearly when they share a token type

Criteria

Without context

With context

Schemes as discrete named contracts

100%

Endpoint maps to one scheme

100%

Separates credential from scheme

100%

Normal vs stepped-up are different schemes

100%

Each endpoint declares requirement

100%

Recommends explicit modelling

100%

56%

Design a payouts endpoint error response

Error response body for a payouts endpoint with three failure modes including a third-party vendor rejection

Criteria

Without context

With context

Unified issues array

100%

Namespaced dot-string issue codes

100%

No separate type field

87%

100%

Severity present

100%

correlationId present

50%

100%

Timestamp present

100%

Third-party error surfaced via object

37%

100%

Descriptive string codes not numeric

100%

Message and links where useful

75%

100%

22%

Unify error handling across REST responses and webhooks

Make error handling consistent across REST and webhooks, with a frontend consumption example

Criteria

Without context

With context

Single shared issues shape

87%

100%

Explains consistency principle

83%

100%

React consumption example

100%

Splits errors vs warnings by severity

83%

100%

Surfaces correlationId

100%

Tolerates unknown codes

83%

100%

Parses class from code

25%

100%

80%

Model a 3DS challenge pause in payment state

Model a 3DS challenge pause without copying Stripe's requires_action status naming

Criteria

Without context

With context

Pushes back on requires_action/pending

100%

Recommends present-condition status

100%

Leads with the missing thing

100%

Actionable part in an issue

100%

Failure loops back

100%

Parseable string over brittle enum

100%

33%

Model an order's status lifecycle and events

Model and name an order's states and events where failed payment is recoverable

Criteria

Without context

With context

State machine first

83%

100%

Separates event, status, issue

62%

100%

Events past-tense on envelope

100%

Status is persistent namespaced string

33%

100%

Flags payment_failed conflation

100%

Recoverable failure loops back

100%

States name present condition

62%

100%

Enum vs parseable string trade-off

100%

Shared grammar with issue codes

100%

93%

12%

Structure a chatty dashboard screen's data access

Decide whether a chatty dashboard screen should fatten the canonical resource or get a view/BFF endpoint

Criteria

Without context

With context

View vs resource distinction

100%

Warns against accreting derived fields

100%

Explains coupling risk

100%

83%

Recommends dedicated view/BFF endpoint

100%

View owns aggregation and formatting

100%

Writes stay on resource endpoints

100%

References a known pattern

50%

100%

78%

Model a multi-actor KYB onboarding lifecycle

Critique a KYB status scheme where a parent segment is both a leaf and a container, for an ownership dashboard

Criteria

Without context

With context

Flags bare parent used as leaf and container

12%

100%

Parent must be pure container or flat leaf

25%

100%

Worst when children terminal

100%

Middle segment is a chosen axis

16%

100%

Group by actor for the dashboard's job

37%

100%

Enables one-segment prefix match

100%

States name present conditions

75%

100%

Evaluated: 8 days ago
Agent: Claude Code
Model: Claude Sonnet 4.6

Table of Contents

Review and improve an ad-hoc error response Present ambiguous auth schemes clearly Design a payouts endpoint error response Unify error handling across REST responses and webhooks Model a 3DS challenge pause in payment state Model an order's status lifecycle and events Structure a chatty dashboard screen's data access Model a multi-actor KYB onboarding lifecycle