Stripe: The API That Became the Standard
Stripe launched in 2010 and immediately became the API that every other API is measured against. The choices Stripe made are worth studying: resource-oriented URLs (/v1/customers/:id), consistent camelCase naming, versioned via URL prefix (/v1/), idempotency keys as first-class primitives (pass a key, Stripe guarantees at-most-once processing), test mode vs live mode toggled by key prefix, and error responses with both machine-readable codes and human-readable messages.
Stripe also understood that API design is documentation design. Their docs were organized by use case rather than by endpoint. 'Accept a payment' walked you through every API call needed. 'Handle refunds' showed the complete flow. The documentation told you not just what the API did but what you were supposed to do with it.
Swagger: Self-Documenting APIs
Tony Tam created Swagger in 2011 at Wordnik. The goal was a machine-readable specification for REST APIs that tools could use to generate documentation, client SDKs, server stubs, and test cases automatically from a single source of truth. A Swagger file described every endpoint, every parameter, every request body schema, every response shape, and every error code.
Swagger became the industry standard for API contracts and was donated to the Linux Foundation in 2015 as OpenAPI Specification. Today, virtually every REST API has an OpenAPI spec. API gateways consume them for routing. Client SDK generators use them. Test frameworks validate against them. The idea Swagger introduced - a contract first, implementation second - transformed how teams design APIs.
OAuth 2.0: Simpler but Different
OAuth 2.0 (RFC 6749, 2012) replaced OAuth 1.0 signing with HTTPS as the security mechanism. No more HMAC signatures. No more nonces. If the transport layer is secure, the request is authenticated by the bearer token it carries. Implementation dropped from hours to minutes. Adoption exploded: Google, Facebook, GitHub, Twitter all moved to OAuth 2.0.
OAuth 2.0's simplification had a cost. OAuth 1.0 tokens were cryptographically bound to the client - a stolen token was useless without the secret. OAuth 2.0 bearer tokens are usable by anyone who has them. HTTPS became a hard requirement. This is a real tradeoff: more accessible but more dependent on transport security being properly configured.
The Grant Types
OAuth 2.0 introduced four authorization grant types for different scenarios. Authorization Code for server-side web apps (still the safest). Implicit for browser-only apps (now deprecated in favor of Auth Code with PKCE). Client Credentials for machine-to-machine. Resource Owner Password Credentials for trusted first-party apps (avoid when possible). Knowing which grant type to use for which scenario is a standard API security interview question.
Stripe's Idempotency Key Design in Detail
Stripe's idempotency key system is one of the most elegant solutions to the at-most-once delivery problem in API design. When a client sends a request with an Idempotency-Key header, Stripe stores the request key and the response. If the same key is sent again (due to a client timeout and retry), Stripe returns the stored response without re-executing the operation. The key expires after 24 hours. This means client code can safely retry any request by including the idempotency key - the worst case is receiving the same response twice.
The client is responsible for generating the key and ensuring it is unique per intended operation. A UUID (v4) is the standard choice. The server is responsible for storing the key and the response and returning the stored response on duplicate requests. This splits the at-most-once guarantee correctly: the client controls retry behavior, the server controls execution uniqueness. Copying this pattern for any API that performs non-idempotent operations (creates, charges, notifications) is one of the most impactful API reliability improvements you can make.
OpenAPI's Role in API-First Development
API-first development reverses the traditional order: design the API contract before writing implementation code. The OpenAPI spec is the design artifact. It is reviewed, iterated on, and approved by all stakeholders before a line of implementation code is written. Mock servers generated from the spec let frontend teams start building against the API immediately, without waiting for backend implementation. This parallelization is one of the biggest productivity gains in the API-first model.
The tooling ecosystem around OpenAPI has matured enough that this workflow is practical. Stoplight, Swagger Editor, and Redoc all provide collaborative spec editing with real-time validation. OpenAPI Generator produces server stubs in FastAPI, Spring, Go, and 40+ other frameworks. Prism and WireMock generate mock servers from specs. The design-first workflow is no longer aspirational - it is the default approach for teams that ship reliable APIs consistently.
- Return 409 Conflict (not 400) when an idempotent request would create a duplicate that violates uniqueness constraints.
- Use 422 Unprocessable Entity for validation errors that are semantically correct HTTP but invalid for your business rules.
- OpenAPI 3.1 aligns with JSON Schema 2020-12 and removes the incompatibilities between OpenAPI's schema dialect and standard JSON Schema.
- Design your error responses to match RFC 7807 (Problem Details for HTTP APIs): type, title, status, detail, instance fields.
- Versioning your OpenAPI spec alongside your code ensures the spec and implementation stay synchronized. Use a CI check to validate the spec against the live API.
The OpenAPI Ecosystem in Production
The OpenAPI ecosystem has matured to the point where it should be part of every API team's workflow. Spectral (Stoplight) is a linting tool that enforces OpenAPI style rules: every endpoint has a description, all responses have schemas, error responses follow RFC 7807 format, parameter names use camelCase. Running Spectral in CI ensures your spec stays clean as the API evolves. Redoc and Scalar generate better-looking documentation than Swagger UI and are worth the 5-minute configuration. openapi-typescript generates TypeScript types directly from your spec, eliminating hand-written type definitions that inevitably drift from reality.
Why Stripe's Documentation Became the Standard
Stripe's documentation influenced every API documentation site that followed it. The key innovations: code samples that automatically adjust to the selected language (curl, Python, Ruby, PHP, JavaScript) without leaving the page; a request/response explorer with real example payloads; documentation organized by use case ('accept a payment', 'handle failed payments') rather than by API endpoint; and an interactive test mode where developers could make real API calls against test data from within the docs. These are not cosmetic improvements - they reduce time-to-first-successful-call from hours to minutes. Every element of Stripe's documentation is a friction-reduction decision. Copy these decisions for your own API documentation.
OAuth 2.0 Security Best Practices in 2024
The OAuth 2.0 security landscape has evolved significantly since the 2012 RFC. The Implicit grant type (designed for browser-only applications) is now deprecated in RFC 9700 because it exposes access tokens in browser history and URLs. The replacement is Authorization Code with PKCE (Proof Key for Code Exchange), which adds a cryptographic challenge to prevent authorization code interception attacks. PKCE is now mandatory for all public clients (mobile apps, SPAs) and recommended for all clients. The Client Credentials grant for machine-to-machine authentication should use rotating client secrets or (better) mTLS certificate-bound tokens to prevent secret exposure.
Stripe's Idempotency Key Design in Detail
Stripe's idempotency key system is one of the most elegant solutions to the at-most-once delivery problem in API design. When a client sends a request with an Idempotency-Key header, Stripe stores the request key and the response. If the same key is sent again (due to a client timeout and retry), Stripe returns the stored response without re-executing the operation. The key expires after 24 hours. This means client code can safely retry any request by including the idempotency key - the worst case is receiving the same response twice.
The client is responsible for generating the key and ensuring it is unique per intended operation. A UUID (v4) is the standard choice. The server is responsible for storing the key and the response and returning the stored response on duplicate requests. This splits the at-most-once guarantee correctly: the client controls retry behavior, the server controls execution uniqueness. Copying this pattern for any API that performs non-idempotent operations (creates, charges, notifications) is one of the most impactful API reliability improvements you can make.
OpenAPI's Role in API-First Development
API-first development reverses the traditional order: design the API contract before writing implementation code. The OpenAPI spec is the design artifact. It is reviewed, iterated on, and approved by all stakeholders before a line of implementation code is written. Mock servers generated from the spec let frontend teams start building against the API immediately, without waiting for backend implementation. This parallelization is one of the biggest productivity gains in the API-first model.
The tooling ecosystem around OpenAPI has matured enough that this workflow is practical. Stoplight, Swagger Editor, and Redoc all provide collaborative spec editing with real-time validation. OpenAPI Generator produces server stubs in FastAPI, Spring, Go, and 40+ other frameworks. Prism and WireMock generate mock servers from specs. The design-first workflow is no longer aspirational - it is the default approach for teams that ship reliable APIs consistently.
- Return 409 Conflict (not 400) when an idempotent request would create a duplicate that violates uniqueness constraints.
- Use 422 Unprocessable Entity for validation errors that are semantically correct HTTP but invalid for your business rules.
- OpenAPI 3.1 aligns with JSON Schema 2020-12 and removes the incompatibilities between OpenAPI's schema dialect and standard JSON Schema.
- Design your error responses to match RFC 7807 (Problem Details for HTTP APIs): type, title, status, detail, instance fields.
- Versioning your OpenAPI spec alongside your code ensures the spec and implementation stay synchronized. Use a CI check to validate the spec against the live API.
The OpenAPI Ecosystem in Production
The OpenAPI ecosystem has matured to the point where it should be part of every API team's workflow. Spectral (Stoplight) is a linting tool that enforces OpenAPI style rules: every endpoint has a description, all responses have schemas, error responses follow RFC 7807 format, parameter names use camelCase. Running Spectral in CI ensures your spec stays clean as the API evolves. Redoc and Scalar generate better-looking documentation than Swagger UI and are worth the 5-minute configuration. openapi-typescript generates TypeScript types directly from your spec, eliminating hand-written type definitions that inevitably drift from reality.
Why Stripe's Documentation Became the Standard
Stripe's documentation influenced every API documentation site that followed it. The key innovations: code samples that automatically adjust to the selected language (curl, Python, Ruby, PHP, JavaScript) without leaving the page; a request/response explorer with real example payloads; documentation organized by use case ('accept a payment', 'handle failed payments') rather than by API endpoint; and an interactive test mode where developers could make real API calls against test data from within the docs. These are not cosmetic improvements - they reduce time-to-first-successful-call from hours to minutes. Every element of Stripe's documentation is a friction-reduction decision. Copy these decisions for your own API documentation.
OAuth 2.0 Security Best Practices in 2024
The OAuth 2.0 security landscape has evolved significantly since the 2012 RFC. The Implicit grant type (designed for browser-only applications) is now deprecated in RFC 9700 because it exposes access tokens in browser history and URLs. The replacement is Authorization Code with PKCE (Proof Key for Code Exchange), which adds a cryptographic challenge to prevent authorization code interception attacks. PKCE is now mandatory for all public clients (mobile apps, SPAs) and recommended for all clients. The Client Credentials grant for machine-to-machine authentication should use rotating client secrets or (better) mTLS certificate-bound tokens to prevent secret exposure.
Stripe's Idempotency Key Design in Detail
Stripe's idempotency key system is one of the most elegant solutions to the at-most-once delivery problem in API design. When a client sends a request with an Idempotency-Key header, Stripe stores the request key and the response. If the same key is sent again (due to a client timeout and retry), Stripe returns the stored response without re-executing the operation. The key expires after 24 hours. This means client code can safely retry any request by including the idempotency key - the worst case is receiving the same response twice.
The client is responsible for generating the key and ensuring it is unique per intended operation. A UUID (v4) is the standard choice. The server is responsible for storing the key and the response and returning the stored response on duplicate requests. This splits the at-most-once guarantee correctly: the client controls retry behavior, the server controls execution uniqueness. Copying this pattern for any API that performs non-idempotent operations (creates, charges, notifications) is one of the most impactful API reliability improvements you can make.
OpenAPI's Role in API-First Development
API-first development reverses the traditional order: design the API contract before writing implementation code. The OpenAPI spec is the design artifact. It is reviewed, iterated on, and approved by all stakeholders before a line of implementation code is written. Mock servers generated from the spec let frontend teams start building against the API immediately, without waiting for backend implementation. This parallelization is one of the biggest productivity gains in the API-first model.
The tooling ecosystem around OpenAPI has matured enough that this workflow is practical. Stoplight, Swagger Editor, and Redoc all provide collaborative spec editing with real-time validation. OpenAPI Generator produces server stubs in FastAPI, Spring, Go, and 40+ other frameworks. Prism and WireMock generate mock servers from specs. The design-first workflow is no longer aspirational - it is the default approach for teams that ship reliable APIs consistently.
- Return 409 Conflict (not 400) when an idempotent request would create a duplicate that violates uniqueness constraints.
- Use 422 Unprocessable Entity for validation errors that are semantically correct HTTP but invalid for your business rules.
- OpenAPI 3.1 aligns with JSON Schema 2020-12 and removes the incompatibilities between OpenAPI's schema dialect and standard JSON Schema.
- Design your error responses to match RFC 7807 (Problem Details for HTTP APIs): type, title, status, detail, instance fields.
- Versioning your OpenAPI spec alongside your code ensures the spec and implementation stay synchronized. Use a CI check to validate the spec against the live API.
The OpenAPI Ecosystem in Production
The OpenAPI ecosystem has matured to the point where it should be part of every API team's workflow. Spectral (Stoplight) is a linting tool that enforces OpenAPI style rules: every endpoint has a description, all responses have schemas, error responses follow RFC 7807 format, parameter names use camelCase. Running Spectral in CI ensures your spec stays clean as the API evolves. Redoc and Scalar generate better-looking documentation than Swagger UI and are worth the 5-minute configuration. openapi-typescript generates TypeScript types directly from your spec, eliminating hand-written type definitions that inevitably drift from reality.
Why Stripe's Documentation Became the Standard
Stripe's documentation influenced every API documentation site that followed it. The key innovations: code samples that automatically adjust to the selected language (curl, Python, Ruby, PHP, JavaScript) without leaving the page; a request/response explorer with real example payloads; documentation organized by use case ('accept a payment', 'handle failed payments') rather than by API endpoint; and an interactive test mode where developers could make real API calls against test data from within the docs. These are not cosmetic improvements - they reduce time-to-first-successful-call from hours to minutes. Every element of Stripe's documentation is a friction-reduction decision. Copy these decisions for your own API documentation.
OAuth 2.0 Security Best Practices in 2024
The OAuth 2.0 security landscape has evolved significantly since the 2012 RFC. The Implicit grant type (designed for browser-only applications) is now deprecated in RFC 9700 because it exposes access tokens in browser history and URLs. The replacement is Authorization Code with PKCE (Proof Key for Code Exchange), which adds a cryptographic challenge to prevent authorization code interception attacks. PKCE is now mandatory for all public clients (mobile apps, SPAs) and recommended for all clients. The Client Credentials grant for machine-to-machine authentication should use rotating client secrets or (better) mTLS certificate-bound tokens to prevent secret exposure.
