api-design-and-contracts

Treat the API as an explicit contract with predictable request, response, and error behavior. Prefer additive evolution such as new optional fields, and call out breaking changes with clear rollout implications before modifying any surface.

Assess consumer impact before changing surfaces and prefer additive changes over modifications to existing fields. When breaking changes are unavoidable, document them explicitly and plan a versioning and rollout strategy.

Validate all incoming data at the API boundary rather than deep in business logic, and avoid ambiguous semantics in field definitions. Keep validation rules aligned with the documented contract shape.

A change is breaking when it alters existing request fields, response shapes, or error behavior that consumers depend on. Removing fields, tightening validation, or changing types all require explicit consumer communication and rollout planning.

Guidance alone does not enforce contracts at runtime; teams still need schema validation, contract tests, or gateway policies to catch violations. This Skill provides design principles, not automated enforcement.