5 Things You Should Know About REST

REST (Representational State Transfer) has been around for over two decades, and while it might sound like old news, it’s still one of the most widely used architectural styles for building APIs. But building a truly reliable, scalable, and maintainable REST API goes beyond just exposing endpoints.

Here are 5 essential things every developer should know about REST:

1. The Maturity of REST

Not all REST APIs are created equal. The Richardson Maturity Model helps us understand the levels of REST compliance:

• Level 0: Single endpoint, typically just RPC over HTTP.

• Level 1: Multiple resources but limited use of HTTP methods.

• Level 2: Proper use of HTTP verbs (GET, POST, PUT, DELETE) and status codes.

• Level 3: Full HATEOAS (Hypermedia as the Engine of Application State), where the API guides the client through available actions.

Most production APIs aim for Level 2 maturity, balancing practicality and usability. While HATEOAS (Level 3) is powerful, many teams find it too complex for day-to-day needs.

👉 Tip: At a minimum, ensure your API correctly uses HTTP methods and returns meaningful status codes.

2. OpenAPI and the API-First Approach

An API-first design means you start with the API contract (specification) before writing any code.

The OpenAPI Specification (OAS) is the de facto standard for describing REST APIs. With it, you can:

• Generate client SDKs in multiple languages.

• Create interactive documentation (e.g., Swagger UI).

• Ensure consistent contracts across teams.

By agreeing on the spec first, developers and consumers stay aligned, reducing integration issues later.

👉 Tip: Use tools like Swagger, Redoc, or Springdoc OpenAPI to generate and maintain your API docs automatically.

3. Validations with Bean Validation

A solid API enforces data integrity. That’s where Bean Validation (JSR 380) comes in.

Instead of manually validating every request field, you can use annotations:

public class UserRequest {
    @NotNull
    private String username;

    @Email
    private String email;

    @Min(18)
    private int age;
}

Frameworks like Spring Boot or Jakarta EE automatically enforce these constraints and return clear error responses.

👉 Tip: Always validate both client input and your own system’s output, ensuring API stability.

4. Versioning Your API

APIs evolve, but breaking clients is never fun. Versioning strategies include:

• URI versioning: /api/v1/users

• Header-based versioning: Accept: application/vnd.myapi.v2+json

• Query parameter versioning: /users?version=2

The most common (and simplest) approach is URI versioning, but choose a method that works for your ecosystem.

If you would like to know more about it, I wrote a dedicated post about it here:

Versioning your API with Spring Framework

👉 Tip: Plan versioning before you need it, so you don’t get stuck with breaking changes later.

5. Observability: Logging, Tracing, and Metrics

A REST API isn’t complete without observability. To diagnose issues and monitor health, integrate:

• Logging: Record structured logs with correlation IDs.

• Tracing: Use OpenTelemetry for distributed tracing to track requests across microservices.

• Metrics: Collect and expose metrics with Micrometer, then visualize them in Prometheus + Grafana.

Observability turns a black-box API into a system you can measure, debug, and improve continuously.

👉 Tip: Standardize logging and tracing across services to make debugging faster.

Final Thoughts

Building a REST API isn’t just about exposing endpoints. By focusing on maturity, specifications, validation, versioning, and observability, you’ll create APIs that are robust, maintainable, and developer-friendly.

What about you?
💬 Which of these do you think is most overlooked in real-world REST APIs? Share your thoughts in the comments!