API Patterns and Practices: REST
Designing REST APIs well, with runnable examples in Quarkus and Python/FastAPI.
What this site is
A chapter-based, hands-on path to designing REST APIs well, built around a single OpenAPI 3.1 contract for a shipping and cargo booking domain. Every hands-on chapter ships the same example in both Quarkus and Python/FastAPI against that one contract, and CI validates both stacks against it — a response that violates the contract fails the build. You work through resource design, HTTP semantics, pagination, async operations, HATEOAS, versioning, streaming and large payloads, then tie the contract to its event side with AsyncAPI, CloudEvents and Arazzo. It assumes you can read Java and Python; it is not a tutorial in either language. All container images are UBI-based, and the stack runs on Docker Compose, minikube, and OpenShift Local.
Prerequisites & the Lab
Get the contract-first toolchain running locally: Quarkus, FastAPI, Docker Compose + LGTM, and the shipping/cargo domain.
Foundations & the decision lens
Decide whether REST fits the interaction in front of you and name the constraint your design choice actually rests on.
Designing resources with a contract
Model a domain as resources and express it as an OpenAPI 3.1 contract that CI enforces against both stacks.
HTTP semantics done right
Return correct status codes, headers and representations, and do partial updates two correct ways: JSON Patch and Merge Patch.
Collections at scale
Design collection endpoints that stay fast and safe under load, and choose a pagination strategy on purpose.
Asynchronous work & jobs
Model work that doesn't finish within one request/response: long-running operations and rerunnable server-owned jobs.
Evolution & lifecycle
Evolve an API without breaking clients and delete under compliance rules: HATEOAS, soft deletion/GDPR purge, and versioning.
Large payloads & streaming
Move large or continuous data over REST with Range requests, chunked transfer, SSE, and NDJSON, and recognize when to leave REST behind.
Performance & transport
Reason about back-end I/O concurrency and HTTP/2-3 behavior behind the API.
Multi-protocol contracts & framework deep-dives
Go deep on OpenAPI, pair it with AsyncAPI, CloudEvents, and Arazzo under one shared schema, then dig into Quarkus REST and FastAPI internals.
Testing
Contract test the API and event schemas, run integration tests across both stacks, then automate with Newman and load testing.
Running it: Docker → minikube → CRC
Run the booking API across three tiers: Docker/Podman Compose with LGTM tracing, Kubernetes on minikube, then OpenShift Local (CRC).
Complete project
The shipping/cargo booking API end to end, every pattern from the book assembled into one both-stack project.