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