Many teams say they build “REST APIs”, but the reality is often a set of HTTP endpoints that behave like remote procedure calls. The difference matters. A mature RESTful design reduces client breakage, improves evolvability, and makes integration work more predictable. If you are building services alongside web or mobile clients-especially in environments where developers rotate between front end, back end, and DevOps-understanding API maturity is a practical skill, not theory. It also complements what developers learn in full stack java developer training, because service contracts and client consumption patterns are central to real-world application delivery.
Why API maturity matters in day-to-day engineering
API maturity is about how well an interface uses HTTP as an application protocol (not just as a transport). Higher maturity tends to deliver:
- Lower coupling between client and server: Clients rely on standard semantics (methods, status codes) and discoverable links rather than memorised URL structures.
- Safer change management: You can add fields, new relations, and new flows without breaking existing consumers.
- Clearer operational behaviour: Caching, idempotency, and retries are easier to implement when endpoints follow HTTP rules.
Importantly, maturity is not “all or nothing”. You can improve incrementally by focusing on semantics, resource modelling, and discoverability.
The Richardson Maturity Model in practice
The Richardson Maturity Model describes four levels (0 to 3). It is best viewed as a roadmap for improving an API.
Level 0: The “one endpoint” approach
At Level 0, an API uses HTTP as a tunnel. You might see a single endpoint, such as/api, that accepts a payload like { “action”: “createOrder” }. This works, but it provides little leverage from HTTP. Errors, caching, and tooling support are limited.
Level 1: Resources
Level 1 introduces resource-based URIs. Instead of “actions”, you model nouns:
- /orders
- /orders/{orderId}
- /customers/{customerId}
This is already a step forward because it encourages consistent naming and a shared mental model across teams.
Level 2: HTTP verbs and status codes
Level 2 is where many “REST” APIs stop. It uses HTTP methods properly:
- GET /orders/{id} retrieves an order
- POST /orders creates an order
- PUT /orders/{id} replaces an order
- PATCH /orders/{id} updates part of an order
- DELETE /orders/{id} deletes an order
It also uses status codes meaningfully: 200, 201, 204, 400, 401, 403, 404, 409, 422, and so on. At this level, you can design idempotent updates, support conditional requests (ETags), and integrate more effectively with standard clients and API gateways.
Level 3: Hypermedia controls (HATEOAS)
Level 3 adds Hypermedia as the Engine of Application State (HATEOAS). This means responses include links that tell the client what it can do next. Instead of hardcoding all workflows, clients follow server-provided links and relations. This is the key to “self-documenting” APIs: the API advertises valid transitions in the current state.
Designing Level 3 APIs with HATEOAS
HATEOAS is easiest when you start with real user flows. For an “order” resource, the available actions depend on the order’s state. A created order might allow payment, but a shipped order might allow tracking only.
Use consistent link relations and state-driven transitions
Include a _links (or similar) section with relation names:
{
“orderId”: “A123”,
“status”: “CREATED”,
“total”: 499.00,
“_links”: {
“self”: { “href”: “/orders/A123” },
“pay”: { “href”: “/orders/A123/pay”, “method”: “POST” },
“cancel”: { “href”: “/orders/A123”, “method”: “DELETE” }
}
}
A shipped order could return different links:
{
“orderId”: “A123”,
“status”: “SHIPPED”,
“_links”: {
“self”: { “href”: “/orders/A123” },
“track”: { “href”: “/orders/A123/tracking”, “method”: “GET” }
}
}
The client now learns permitted actions from the representation. That is the practical advantage: fewer brittle assumptions about server workflows.
Pick a representation style and stick to it
Common approaches include HAL, JSON: API, and Siren-like patterns. The specific format matters less than consistency. Define:
- How links are represented
- How to indicate allowed methods (if you choose to)
- How to represent embedded sub-resources
- How errors are structured (including validation details)
Treat documentation as a complement, not a substitute
HATEOAS reduces the need for clients to memorise URLs, but you still need:
- A contract for fields and semantics
- Security requirements (auth scopes, roles)
- Rate limits and operational constraints
- Example flows and error cases
For many teams, the best approach is OpenAPI for baseline documentation plus hypermedia for runtime discoverability.
Common pitfalls and pragmatic guidance
- Over-linking everything: Provide links that represent meaningful state transitions. Do not flood responses with dozens of rarely used relations.
- Ignoring caching and conditional requests: Level 2/3 designs benefit from ETags and If-Match for safe updates, and cache headers for read-heavy resources.
- Inconsistent error semantics: Standardise error bodies, use 409 for conflicts, 422 for validation failures (when applicable), and include correlation IDs for troubleshooting.
- Versioning too early via URLs: Prefer compatible evolution (adding fields, new links) first. When breaking changes are unavoidable, consider media-type versioning or well-governed path versioning.
- Not testing workflows: Add contract tests that verify not just fields, but also which links appear for each state. This is where many Level 3 attempts fail.
Teams that build APIs for long-lived products often find that Richardson Level 3 aligns well with real service evolution, and it reinforces the design discipline expected in full stack java developer training where back-end services must stay reliable as front ends change.
Conclusion
The Richardson Maturity Model provides a clear path from basic HTTP usage to genuinely RESTful services. Level 1 improves modelling, Level 2 improves correctness and tooling leverage, and Level 3 (HATEOAS) improves evolvability by making valid actions discoverable from responses. You do not need to jump straight to Level 3 everywhere. Start by modelling resources well, use HTTP semantics properly, then add hypermedia where state-driven workflows and change resilience matter most.