liveBook · Manning

Api style

As explained in Microservices Patterns, Second Edition

An API style guide is an organization-wide set of conventions for designing, naming, documenting, securing, and evolving APIs.

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.
rest api breaking changes

A breaking API change can support both old and new versions during a deprecation period, allowing clients time to update. section 8.2.2

How Microservices Patterns, Second Edition covers it

How deep it goes
Lists REST convention areas and describes Service Chassis enforcement without prescribing a complete set of rules.
Examples
Uses a Java backend and AngularJS frontend integration failure and points to the Adidas API Guidelines.
What you can do after
Evaluate shared API conventions and identify decisions a REST style guide should address.
How it connects
Connects API-first design, interface definitions, OpenAPI, REST, and Service Chassis.

Also explained in

Compare how 2 books explain api style →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Microservices Patterns, Second Edition. The section links point to the parts of the book it draws on.