pproenca/dot-skills/stripe-inspired-api-design-rules

Stripe-Inspired API Design Best Practices

A reference distillation of the design conventions behind Stripe's API — the most widely admired and copied JSON HTTP API in the industry. Contains 52 actionable rules across 8 categories, prioritised by how irreversibly a wrong decision cascades through every endpoint, every SDK, and every client integration. Each rule explains the WHY, shows incorrect-vs-correct code, and links to the canonical source.

When to Apply

Reach for this skill when:

• Designing a new JSON HTTP API or a new endpoint on an existing one
• Reviewing an API design proposal, OpenAPI spec, or PR that adds/changes endpoints
• Debugging an integration where the "wrong" shape of the API is causing client bugs
• Auditing an API for naming consistency, error shape uniformity, or compatibility risks
• Producing an API design report (the kind your inspector tool emits — Critical / Warning / Suggestion / Positive)
• Picking between two designs and looking for an authoritative source to back the choice
• Onboarding to API design — these are the canonical patterns to internalise first

The rules are general — they apply to any JSON HTTP API, not just APIs imitating Stripe. Triggers include "API design", "OpenAPI", "endpoint", "schema", "webhook", "idempotency", "pagination", "API versioning", and reviews of YAML/JSON spec files.

Rule Categories by Priority

Earlier categories cascade harder: a wrong choice in resource modeling (numeric IDs, no object discriminator) propagates to every endpoint forever; a wrong choice in webhook event naming is a single category to fix.

Quick Reference

1. Resource Modeling & Identifiers (CRITICAL)

• `resource-prefixed-string-ids` — Use Prefixed String IDs for Every Resource
• `resource-object-discriminator` — Include a Read-Only object Discriminator on Every Resource
• `resource-opaque-ids` — Treat IDs as Opaque Strings up to 255 Characters
• `resource-unix-seconds-timestamps` — Use Unix Seconds (Integer) for All Datetimes
• `resource-iso-date-only` — Use ISO 8601 Date Strings for Date-Only Values
• `resource-birthdate-hash` — Represent Birth Dates as {day, month, year} Hashes
• `resource-integer-minor-units` — Use Integer Minor Units for Money, Never Floats
• `resource-currency-field-not-name` — Colocate a currency Field; Never Bake Currency into Field Names
• `resource-decimal-suffix-strings` — Use _decimal String Suffix for Precise Decimals That Can't Be Integers

2. URL Structure & HTTP Semantics (CRITICAL)

• `url-plural-collections` — Pluralize Collection URLs; Singularize Object Types
• `url-post-for-updates` — Use POST for Updates (Not PUT or PATCH)
• `url-action-verbs-as-subpaths` — Express Non-CRUD Actions as Imperative Sub-Paths
• `url-no-bulk-endpoints` — One Object Per Request — No Bulk Endpoints
• `url-version-in-path-and-header` — Version in URL Path and Stripe-Version Header
• `url-dedicated-search-endpoint` — Use a Dedicated /search Endpoint for Complex Queries

3. Request & Response Format (HIGH)

• `format-form-encoded-requests` — Accept Form-Encoded Requests, Always Return JSON
• `format-bracket-notation-nesting` — Use Bracket Notation for Nested Fields in Form Bodies
• `format-list-envelope` — Return Lists in a {object, url, has_more, data} Envelope
• `format-cursor-pagination` — Paginate by Cursor (starting_after/ending_before), Not by Offset
• `format-no-total-counts` — Use has_more Boolean; Never Return Total Counts
• `format-expand-parameter` — Expand Related Objects with expand[] in One Round Trip
• `format-dot-notation-expansion` — Allow Dot-Notation for Nested Expansion (Max Depth 4)

4. Errors & Status Codes (HIGH)

• `error-top-level-object` — Always Wrap Failures in a Top-Level error Object
• `error-four-type-enum` — Use a Small Fixed type Enum, Don't Proliferate Types
• `error-message-mandatory-code-optional` — Require message; Make code Optional and Only for Programmatic Handling
• `error-lowercase-snake-case-codes` — Use Lowercase snake_case for Error Codes, Not SCREAMING_SNAKE_CASE
• `error-http-status-mapping` — Map Error Types to HTTP Status Codes Consistently
• `error-doc-url-on-every-error` — Include doc_url Links and Request IDs on Every Error

5. Idempotency & Safe Retries (HIGH)

• `idem-key-header` — Accept Idempotency-Key Header on All Mutating Requests
• `idem-scoped-per-account` — Scope Idempotency Keys per Account, Not Globally
• `idem-24h-ttl` — Keep Idempotency Keys for 24 Hours, Reap at 72
• `idem-fail-on-key-reuse` — Return 409 When a Key Is Reused with Different Params
• `idem-recovery-points` — Use Recovery Points for Multi-Step Idempotent Operations

6. Versioning & Backwards Compatibility (HIGH)

• `ver-dated-versions` — Use Dated Versions (YYYY-MM-DD), Not v1/v2/v3
• `ver-account-pinning` — Pin Each Account to Its First-Request Version
• `ver-additive-changes` — Define What Counts as a Backwards-Compatible Change
• `ver-version-change-modules` — Encapsulate Each Breaking Change in a Version-Change Module
• `ver-tolerate-unknown` — Document That Clients Must Tolerate Unknown Fields, Events, and Enum Values

7. Naming, Polymorphism & Metadata (MEDIUM-HIGH)

• `naming-snake-case-wire-format` — Use snake_case for All Wire Identifiers
• `naming-american-english` — Use American English Spelling (canceled, Not cancelled)
• `naming-simple-unambiguous` — Names — Simple, Unambiguous, No Leading Digits, No Jargon
• `naming-type-discriminator-polymorphism` — Discriminate Polymorphic Types with a type Field and Sibling Objects
• `naming-metadata-pattern` — Provide a metadata Pass-Through with Strict Limits
• `naming-boolean-past-tense` — Booleans — Past-Tense Verbs and Plain Adjectives, Not is_/has_ Prefixes
• `naming-enums-over-booleans` — Prefer Enums over Booleans for New Status/Flag Fields

8. Authentication, Webhooks & Search (MEDIUM-HIGH)

• `ops-prefixed-api-keys` — Prefix API Keys with Scope and Mode (sk_live_, pk_test_, rk_)
• `ops-https-only-basic-auth` — Enforce HTTPS Only and Use HTTP Basic Auth with the Key as Username
• `ops-on-behalf-of-header` — Use a Dedicated On-Behalf-Of Header for Multi-Tenant Calls
• `ops-webhook-event-envelope` — Webhook Events Use a Fixed {id, object, type, data, created} Envelope
• `ops-webhook-event-naming` — Event Type Naming — <resource>.<past_tense_action>
• `ops-webhook-signature` — Sign Webhook Deliveries with HMAC and a Timestamp Tolerance Window
• `ops-webhook-at-least-once-handlers-idempotent` — Document At-Least-Once Delivery; Handlers Must Dedupe on event.id

How to Use

For a focused question ("should this field be a boolean or an enum?"), jump directly to the relevant rule (naming-enums-over-booleans) — each rule is self-contained with the WHY, code examples, and the canonical source.

For a full API review or audit, work through the categories top-to-bottom. The order matches Stripe's own design priority: get resource modeling and URL structure right first; format, errors, idempotency, and versioning are the next layer; naming and operational surface come last because they're the easiest to evolve.

For producing a structured findings report (the kind an inspector tool emits), cite rules by their slug — resource-unix-seconds-timestamps, format-no-total-counts — so each finding traces back to a specific, defensible source.

Read section definitions for the cascade-impact rationale behind the category ordering, or the rule template when adding a new rule.

Reference Files