An API style guide defines organization-wide conventions for APIs. It helps independently developed services remain predictable, discoverable, and easy to use, reducing the integration friction that arises when teams make different choices for recurring design decisions. section 8.1.2
A guide complements API-first design: define an interface, review it with client developers, iterate, and then implement the service. The guide supplies shared conventions; an interface definition describes a particular API. For REST, an OpenAPI document can describe endpoints, methods, and request and response bodies. section 8.1.2 section 8.2.2
A REST API style guide should address recurring decisions that HTTP leaves open:
- Resource modeling, URL structure, HTTP methods and status codes, query parameters, filtering, and pagination. section 8.2.2
- Request and response structures, naming, envelopes, and error formats. section 8.2.2
- Authentication, headers, content negotiation, versioning, documentation, deprecation, and security. section 8.2.2
Shared conventions can simplify documentation, tooling, and automated validation. A Service Chassis can enforce and automate cross-cutting aspects through reusable components such as standardized error responses, authentication filters, and logging and tracing interceptors. section 8.1.2
An interface mismatch
A Java backend and an AngularJS frontend were each considered complete, but the application did not work: their REST and WebSocket API was poorly defined. Reviewing the interface with client developers before implementation helps expose such disagreements earlier. section 8.1.2
Figure 8.6 A service must implement a breaking API change by supporting both the new and old versions of the API for the deprecation period. Clients that haven’t yet been updated can use the old version.
A breaking API change can support both old and new versions during a deprecation period, allowing clients time to update. section 8.2.2

