An API is a public software interface and a durable contract between its provider and the systems or clients that depend on it. Its documentation must make operations, constraints, assumptions, and expected behavior understandable. section 9.4.1
A durable API contract commonly specifies:
- Public operations, parameters, input and output formats, and error responses. section 9.4.1
- Limits such as rate limits, response sizes, pagination, performance expectations, and required configuration. section 9.4.1
- Authentication, access control, versioning, and deprecation policies. section 9.4.1
- Only the smallest necessary public surface, with implementation details hidden behind clear response models. section 9.4.1 section 9.5
Avoid leaking the data model
Returning database entities directly from a REST API exposes internal structure, couples clients to the database schema, and can disclose private information. A separate response model reduces that exposure and preserves freedom to change internals. section 9.4.1 section 9.5
