# Documentation, SDKs and API Governance — API Design and Versioning

Source: https://www.geekswithgeeks.com/en/api-design/qg-docs-governance

> Document for developers, ship SDKs and keep many teams consistent with a style guide and reviews.

## 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.

```text
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.
```

**Quiz:** What is the aim of API governance?

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

*Answer:* Consistent, high-quality APIs across teams without blocking delivery. Shared standards and light review keep APIs coherent and easy to adopt.