stripe-api-design

Installation
SKILL.md

Stripe-Style API Design

Stripe's API is the modern reference standard for developer-facing REST APIs. This skill captures the conventions, decision frameworks, and design tradeoffs that make their API feel inevitable — predictable resources, painless pagination, exactly-once writes, and indefinite backward compatibility.

Apply these patterns when you are designing the public surface of any system: a SaaS REST API, an internal platform API, a webhook system, or a typed SDK. The goal is an API that integrators can learn once and reason about everywhere.


The Core Philosophy

APIs are products. Developers are the customers.

Every other rule in this skill flows from that single sentence. It implies:

  1. Optimize for the integrator's first hour and tenth year. A new developer should grasp the API by reading three endpoints. A ten-year customer should never have to rewrite working code.
  2. Predictability beats cleverness. If /customers works one way, /charges must work the same way. Surprise is a defect.
  3. Each endpoint is a permanent contract. Once it ships, you support it forever. Design accordingly — slowly, with review, and with a versioning escape hatch.
  4. Errors are part of the product. A confusing error message is a UX bug, not a server log line.
  5. Make the right thing the easy thing. Idempotency keys, expand, metadata — the API should make robust integrations trivial and fragile ones harder than necessary.
Installs
1
First Seen
May 8, 2026