liveBook · Manning

Rest api

As explained in Microservices Patterns, Second Edition

An HTTP-based application programming interface that exposes resources according to REST constraints.

REST APIs carry communication across process boundaries in microservice architectures. Choosing them affects availability, performance, and runtime coupling, so weigh those forces against alternatives such as asynchronous messaging. section 8.0

A REST API exposes endpoints with HTTP methods, parameters, and request and response bodies. At the HATEOAS level, a resource representation includes links for actions, such as canceling an order; clients can follow those links instead of hard-wiring URLs. section 8.2.2

OpenAPI provides a machine-readable API contract covering endpoints, methods, parameters, bodies, and authentication. Tools can use it to generate client SDKs, server stubs, documentation, and tests. Framework metadata can also generate the document, keeping it aligned with the implementation. section 8.2.2

Figure 8.5 An OpenAPI document describes a REST APIs endpoints including URL paths, HTTP methods, request and response bodies, and so on.
rest open api doc

Use the diagram to see the endpoint, method, and request and response details represented in an OpenAPI document. section 8.2.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

For a breaking API change, support old and new versions during deprecation so clients can migrate without an immediate cutover. section 8.2.2

How Microservices Patterns, Second Edition covers it

How deep it goes
Details HATEOAS action links and OpenAPI contract fields, tooling, and generation from framework metadata.
Examples
Uses order cancellation through a resource link and Spring Boot with SpringDoc to generate OpenAPI documents.
What you can do after
Evaluate REST APIs by maturity level and define OpenAPI contracts for generating SDKs, server stubs, documentation, or tests.
How it connects
Links REST to interprocess communication, asynchronous messaging, HATEOAS, and OpenAPI.

Also explained in

Compare how 4 books explain rest api →

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.