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.
96
90%
Does it follow best practices?
Impact
99%
1.70xAverage score across 8 eval scenarios
Passed
No known issues
criteria.jsonevals/scenario-7/
{
"context": "The user is tempted to accrete screen-specific, derived fields onto the canonical /customers/{id} resource to de-chatty a dashboard. The criteria check whether the answer distinguishes view/BFF endpoints from canonical resource endpoints and steers UI-shaped aggregation into a dedicated view layer.",
"type": "weighted_checklist",
"checklist": [
{
"name": "View vs resource distinction",
"description": "Explicitly distinguishes view/presentation endpoints from canonical resource endpoints",
"max_score": 8
},
{
"name": "Warns against accreting derived fields",
"description": "Warns against adding UI-specific/derived fields (outstanding balance, formatted label) onto the canonical /customers/{id} resource",
"max_score": 8
},
{
"name": "Explains coupling risk",
"description": "Explains the underlying risk: accreting screen fields couples the platform/canonical API to one specific screen",
"max_score": 6
},
{
"name": "Recommends dedicated view/BFF endpoint",
"description": "Recommends a dedicated view/BFF endpoint that aggregates and formats for that screen, sitting over the resource layer",
"max_score": 8
},
{
"name": "View owns aggregation and formatting",
"description": "Notes the view endpoint is where aggregation and presentation (balance, formatted next-action label) live, owned by/for the frontend",
"max_score": 6
},
{
"name": "Writes stay on resource endpoints",
"description": "Notes that writes/mutations still go to the canonical resource endpoints, not the view endpoint",
"max_score": 4
},
{
"name": "References a known pattern",
"description": "References an established pattern by name (BFF, GraphQL, or CQRS) as supporting context",
"max_score": 4
}
]
}