API Documentation
OpenAPI as a machine-checked contract rather than as prose.
4 to work through
-
intermediate
A team generates its entire API reference from code annotations and deletes the hand-written guide. Six months later integrators are opening more support tickets, not fewer, and every one of them is technically answerable from the reference. What did generation buy, and what did it destroy?
2 min answer -
intermediate
A workspace platform's API is well designed but developers repeatedly build integrations that break under real conditions. What is missing from the documentation, and what should be added?
2 min answer -
intermediate
Why is documenting an API's failure and retry semantics more important than documenting its success behaviour?
2 min answer -
intermediate
Your platform has 60 internal APIs. Teams repeatedly rebuild capabilities that already exist because they cannot find or understand them. What do you build?
2 min answer
2 terms in this topic
API Documentation
Documentation as part of the product surface — where quality determines adoption more than the API's technical design does.
practiceSpec-First Development
Writing and reviewing the API specification before implementing, so the contract is designed deliberately rather than emerging from code.
Neighbouring topics
API & Integration
General material on integrating systems through contracts.
REST Design
Resources, uniform methods, status codes and statelessness.
GraphQL
Client-specified queries, N+1 resolution and query-cost control.
gRPC APIs
Contract-first RPC, generated clients and protobuf compatibility rules.
Webhooks
Push callbacks, signature verification, ordering and at-least-once delivery.
API Versioning
URL, header and account-pinned versioning, and who carries the burden.
Backward Compatibility
Which changes are safe, and how to make breakage a build failure.
Contract Testing
Verifying what consumers actually rely on, without a shared environment.
Rate Limiting
Algorithms, shared counters, and signalling rejection properly.
Idempotency Keys
Client-generated keys stored atomically with the operation they guard.
Pagination & Filtering
Offset versus cursor, stable ordering and unbounded result sets.
API Error Handling
Error shapes, retryability signals and machine-readable causes.
Event-Driven Integration
Publishing facts rather than commands, and versioning event schemas.
Message Formats
JSON, Protobuf, Avro — schema evolution and payload economics.
Schema Registry
Enforcing compatibility on events the way CI enforces it on code.
Integration Patterns
Routers, translators, splitters, aggregators and dead letter channels.
Legacy Integration
Reaching systems that cannot change, without importing their model.
Partner & B2B Integration
External contracts, onboarding, sandboxes and long deprecation windows.
APIs as Products
Ownership, lifecycle, deprecation policy and developer experience.