Documentation, SDKs and API Governance

The developer experience is the product

Good docs have a quick start that makes a first successful call in minutes, reference generated from the OpenAPI spec, guides for common tasks, runnable examples in several languages, an honest changelog and an error catalogue. Offer a sandbox with test data and keys. SDKs generated or hand-crafted for popular languages hide authentication, retries, pagination and idempotency; version and test them like the API itself. With many teams, add governance: a written API style guide (naming, errors, pagination, versioning), automated linting of specs (for example with Spectral rules), an API review step before new endpoints ship, a central catalogue of APIs and owners, and metrics such as latency, error rate, adoption and time-to-first-call. Governance should enable teams to ship consistently, not slow them down.

A style-guide excerpt

Short, testable rules are easy to lint and easy to follow.

1. Paths: lowercase, plural nouns, hyphen-separated; max 2 levels of nesting.
2. JSON fields: snake_case; timestamps in ISO 8601 UTC; money as integer minor units + currency.
3. Collections: cursor pagination, default limit 20, max 100; next_cursor null at the end.
4. Errors: application/problem+json with type, title, status, detail, request_id.
5. POST with side effects requires Idempotency-Key.
6. Breaking changes need a new major version, a migration guide and 6 months' notice.
7. Every operation has operationId, summary, error responses and an example.

Quick check: What is the aim of API governance?

• To remove documentation
• To slow down all releases
• Consistent, high-quality APIs across teams without blocking delivery
• To avoid versioning forever