Documentation and contract testing

Durable APIs protect consumers with **accurate docs**, **worked examples**, and **automated contract checks** — not hope that teams read Slack threads.

Documentation essentials:

• Quickstart with auth and first successful call.
• Error catalog tied to stable codes.
• Changelog with deprecation dates.
• OpenAPI/GraphQL schema published from the same artifact CI validates.

Contract testing layers:

• **Provider tests**: implementation matches published schema (response validation).
• **Consumer-driven contracts** (Pact): consumer expectations recorded; provider verifies fixtures.
• **Compatibility CI**: diff OpenAPI/proto on PR; fail on breaking changes without major version.

					// Supertest + schema assertion example
const res = await request(app).get('/orders/1').expect(200);
expect(res.body).toMatchSchema(orderSchema);
				

Mocks: generated from OpenAPI (Prism, MSW handlers) for parallel development — refresh when spec changes.

On interviews: difference between contract tests and broad E2E, who owns the contract in microservices, and preventing spec drift.

Common pitfalls: docs lagging code, examples that never run in CI, pact tests that nobody updates, and breaking changes without consumer notification.

The trade-off is CI time versus integration surprises — contract tests are cheaper than production outages.

Checklist:

• Examples executed in CI where possible.
• Breaking-change detection on schemas.
• Consumer fixtures or pact for cross-team APIs.
• Changelog + deprecation policy published.