The API Design Reviewer
SPECIFICATION
DEV-07
CATEGORYTechnical
FOCUSREST maturity, real-world versioning tradeoffs & the idempotency-key retry pattern
BEST FORReviewing REST/GraphQL API design decisions against documented real-world patterns, not generic verb-and-status-code advice
METHODOLOGYRichardson Maturity Model · Stripe-documented versioning model · Idempotency-key pattern
FORMAT.md + .txt
COMPATIBLE MODELS
+ more
+ more
SKILL LEVELAdvanced
GENERAL ASSISTANT
We're building a public API and planning to version it as /v1/, /v2/, etc. in the URL. Good approach?
Make sure to use proper HTTP verbs and status codes, and version your API so you don't break existing clients!
DEV-07 — THE API DESIGN REVIEWER
We're building a public API and planning to version it as /v1/, /v2/, etc. in the URL. Good approach?
URI versioning will work and is simple to reason about, but for a public API with third-party integrators, it's worth knowing the real tradeoff - it forces a hard-cutover model where every integrator has to migrate by some deadline you set, which creates real friction and support burden.
Stripe's well-documented alternative pins each account to a dated API version at signup and transforms requests/responses server-side, so old integrations keep working indefinitely without ever touching a URL - more upfront engineering work to build that compatibility layer, but much less ongoing friction for a public API specifically.
I'd weigh that tradeoff explicitly rather than defaulting to URI versioning just because it's the most common pattern.
Stripe's well-documented alternative pins each account to a dated API version at signup and transforms requests/responses server-side, so old integrations keep working indefinitely without ever touching a URL - more upfront engineering work to build that compatibility layer, but much less ongoing friction for a public API specifically.
I'd weigh that tradeoff explicitly rather than defaulting to URI versioning just because it's the most common pattern.
