DEV Community: Hai Nguyen

RESTful API: Why Is It Still the Standard for Web APIs?

Hai Nguyen — Sat, 21 Mar 2026 09:54:14 +0000

Imagine walking into a fine restaurant. You raise your hand, and a waiter comes to take your order along with your table number. The waiter delivers the request to the kitchen, and a few minutes later returns with the dish you asked for.

You don’t need to know how the kitchen works, you only care that your order arrives correctly. Meanwhile, many other waiters are serving many other tables at the same time.

If this sounds familiar, it’s because this is a common analogy used to explain how APIs work.

In the world of software, an API acts much like the waiter in this story. The client sends a request describing what it needs, the server processes that request, and then returns the result. The client does not need to understand the internal implementation of the server, only how to communicate with it.

One of the most widely used approaches for building web APIs today is the REST architecture style. REST leverages the widely adopted HTTP protocol to standardize how clients request resources and how servers respond, typically using lightweight data formats such as JSON.

Because of its simplicity, scalability, and compatibility with the web, RESTful APIs have become the de facto standard for modern web services.

What is RESTful API ?

Beginners often confuse REST with RESTful APIs due to how people casually use the term “REST API.”

To clarify:

REST is a set of architectural principles
RESTful API is an API that follows those REST principles In short, a RESTful API is simply an API designed according to REST constraints.

REST like a blueprint while RESTful Api is the iplementation

Principle 1: Client–Server

This is the most fundamental principle.
Client and server are separated into independent entities. This allows one or multiple servers to serve one or many clients simultaneously.
This separation decouples the user interface from the business logic, making it possible to update either side without affecting the other.

Benefits:

Easier to maintain
Can scale independently
Frontend and backend teams can work separately

Principle 2: Stateless

The server does not store any previous request state.
Each request is independent and must contain all necessary information (e.g., authentication token, resource identifiers).
This makes the system more scalable and reliable because any server can handle any request.

Compare to stateful api, request depend on state of last request
Server save state of client between requests

For example:
With stateless, after login request was sent to server with all informations like token, resource.. server don't need to remember last request, it just handle current request
With stateful, after login, server need to create a session to save save your login session, if session was forget, you log out.

Benefits

Eazy to scale
Better performance
Better for loadalancing ...

Principle 3: Cacheable

Server responses can be cached.
REST allows clients (apps, browsers) or intermediaries (proxies) to store responses temporarily.
Benefits:

Reduce the number of requests to the server
Improve response time
Save bandwidth

Principle 4: Uniform Interface

This is the most important principle of REST.
It defines a consistent way to interact with resources.
Each resource should have a unique URL:

Get all users → /users
Get a specific user → /users/1

Avoid using action-based URLs like:

/getUser
/createUser

REST leverages HTTP methods to define actions:

GET → retrieve data
POST → create new data
DELETE → remove data
PUT → update entire resource
PATCH → update partial resource

Resource Representation
The server does not return raw objects or database records directly.
Instead, it returns a representation of the resource, typically in formats like JSON or XML.
For example, when building a RESTful API with Spring Framework, the backend does not expose Java objects directly—it returns JSON representations.

{ "id": "8f3c2a9e-5b1d-4c7a-9f2e-1a6b3d8c4e10", "username": "john_doe92", "email": "john.doe92@example.com", "firstName": "John", "lastName": "Doe", "phone": "+1-202-555-0147", "dateOfBirth": "1992-06-15", "gender": "male" }

This standardization allows different systems to communicate consistently.

Benefits:

Standardization comunication (commonly json/xml)
Security (pass nessary information in request/response)
api versioning

Principle 5: Layered System

Clients do not need to know whether they are communicating directly with the main server or through intermediaries.
In modern architectures (especially microservices), requests often pass through multiple layers:

For example:
Browser → CDN → Gateway → Load Balancer → Security → Business Service → Database
The client only needs to know the endpoint.

Benefits:

Easier scaling
Better maintainability
Independent services
Improved performance via load balancing

Principle 6: Code on Demand (Optional)

Instead of sending only data (JSON/XML), the server can send executable code for the client to run.
However, this approach is rarely used in modern APIs and is generally not recommended.

Compare to other style of API

REST is a very good style of API, but not all time we use it

With out REST, there are many style of API like GraphQL, gPRC...
Get gPRC for example, if you need a hign performance or realtime streaming
Try to compare REST and gPRC

Final Thoughts

From a developer’s perspective, REST is not a protocol but a design philosophy.
Understanding and applying these principles correctly will help you build APIs that are scalable, maintainable, and easy to use.
A RESTful API is simply the practical implementation of those ideas.

Validating REST API Requests in Spring Boot in practice

Hai Nguyen — Sun, 28 Dec 2025 10:53:18 +0000

Why validation belongs at the API boundary

Imagine an API endpoint that accepts user input without any validation. One day, a client sends a request with a negative amount, an invalid email, and missing required fields. The request still reaches the service layer, corrupts business logic, and causes unexpected errors deep inside the system. The bug is hard to trace, not because the logic is complex, but because invalid data was never stopped at the boundary.

What happens when a request arrives (overview)

When a client sends an HTTP request to a Spring Boot application, a small pipeline runs before your controller code executes. Understanding that pipeline explains where validation belongs and when exceptions are thrown:

DispatcherServlet receives the request and resolves a controller handler.
Spring prepares method invocation by resolving method arguments. For @RequestBody, it uses an HttpMessageConverter to deserialize JSON into the target DTO.
During argument resolution, Spring integrates Jakarta Bean Validation (Hibernate Validator by default). If a controller parameter is annotated with @Valid or the controller is annotated with @Validated, the deserialized DTO is validated automatically. If any constraint violations are found, Spring raises a validation exception and does not invoke the controller method body.
The thrown exception is then routed through Spring's exception resolution mechanism, where application level handlers decide the HTTP response.

Common validation exceptions you should know
MethodArgumentNotValidException: Raised when validating an @RequestBody fails (field-level or object-level violations). This exception carries the binding result with field errors and rejected values.
ConstraintViolationException: Raised when method parameter validation (@Validated on parameters, @RequestParam, @PathVariable, or programmatic validator calls) fails. The exception contains a set of ConstraintViolations describing each failure.
HttpMessageNotReadableException: Raised when JSON parsing fails (malformed JSON) before validation even runs.
These exceptions are thrown before your controller logic runs. The responsibility for shaping the HTTP response falls to the configured exception handlers.

Below are the simple code snippets that illustrate how validation is declared and enforced.

// Request DTO (contract and annotations)

public class RequestPayload {
    @NotBlank
    private String name;

    @Email
    @NotBlank
    private String email;

    @NotBlank
    @DepartmentCodeValid
    private String departmentCode;
}

Notes: the DTO declares both standard constraints (@NotBlank, @Email) and the custom domain constraint (@DepartmentCodeValid) directly on the field. This keeps the data contract and validation rules colocated and self documenting.

// Custom constraint annotation

@Documented
@Constraint(validatedBy = DepartmentCodeValidator.class)
@Target({FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface DepartmentCodeValid {
    String message() default "departmentCode must be one of 50..99";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

// Custom validator implementation
// this validator constrains that `departmentCode` must be in the 
// defined codes

public class DepartmentCodeValidator implements ConstraintValidator<DepartmentCodeValid, String> {
    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        if (value == null || value.isBlank()) {
            return false;
        }
        try {
            int code = Integer.parseInt(value);
            for (DepartmentCode dc : DepartmentCode.values()) {
                if (dc.getCode() == code) {
                    return true;
                }
            }
            return false;
        } catch (NumberFormatException e) {
            return false;
        }
    }
}

// Domain enumeration of allowed department codes

public enum DepartmentCode {
    CODE_50(50),
    CODE_98(98),
    ...
    CODE_99(99);

    private final int code;

    DepartmentCode(int code) {
        this.code = code;
    }

    public int getCode() {
        return code;
    }
}

// Controller that accepts the request

@RestController
@RequestMapping("/api/requests")
public class RequestController {
    private final CacheService cacheService;

    public RequestController(CacheService cacheService) {
        this.cacheService = cacheService;
    }

    @PostMapping
    public ResponseEntity<RequestPayload> create(@Valid @RequestBody RequestPayload payload) {
        var saved = cacheService.save(payload);
        return ResponseEntity.ok(saved);
    }
}

How validation failure is raised and routed (walkthrough)

When the POST handler receives a request, Spring deserializes the JSON body into RequestPayload.
Because the create method parameter is annotated with @Valid, the bean validation engine runs automatically.
The engine executes built-in constraints (@NotBlank, @Email) and the custom DepartmentCodeValidator.
If the custom validator rejects the departmentCode (or any other constraint fails), the engine records violations and Spring throws MethodArgumentNotValidException.
Spring's HandlerExceptionResolver chain (including any @RestControllerAdvice) receives that exception and decides how to convert it into an HTTP response. The controller method body is never invoked.

Centralizing validation error handling recommended

Below is an illustrative GlobalExceptionHandler you can adopt in the project. It is shown inline here to demonstrate how the binding errors and constraint violations can be transformed into a stable JSON error envelope.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ValidationErrorResponse> handleBindingErrors(MethodArgumentNotValidException ex,
                                                                       HttpServletRequest request) {
        List<FieldError> errors = ex.getBindingResult().getFieldErrors().stream()
            .map(fe -> new FieldError(fe.getField(), fe.getDefaultMessage(), fe.getRejectedValue()))
            .collect(Collectors.toList());

        ValidationErrorResponse body = new ValidationErrorResponse(
            OffsetDateTime.now(), HttpStatus.BAD_REQUEST.value(), request.getRequestURI(), errors
        );
        return ResponseEntity.badRequest().body(body);
    }

    // Example: handle type mismatches or malformed values for query/path params
    @ExceptionHandler({ MethodArgumentTypeMismatchException.class })
    public ResponseEntity<ValidationErrorResponse> handleTypeMismatch(MethodArgumentTypeMismatchException ex,
                                                                      HttpServletRequest request) {
        FieldError err = new FieldError(ex.getName(), "invalid value", ex.getValue());
        ValidationErrorResponse body = new ValidationErrorResponse(
            OffsetDateTime.now(), HttpStatus.BAD_REQUEST.value(), request.getRequestURI(), List.of(err)
        );
        return ResponseEntity.badRequest().body(body);
    }

    // Add other handlers (ConstraintViolationException, HttpMessageNotReadableException, etc.) as needed
}

// Minimal helper DTOs used above 
record FieldError(String field, String message, Object rejectedValue){}
record ValidationErrorResponse(OffsetDateTime timestamp, int status, String path, List<FieldError> errors) {}

Notes on the example handle

The handler reads field errors from the binding result and maps them to a compact FieldError structure. This is the most direct way to surface which property failed and why.
The same pattern can be applied to ConstraintViolationException by mapping each ConstraintViolation to a field/property path.
A consistent error envelope returned by the global handler might look like:

{
  "timestamp": "2025-12-28T12:34:56Z",
  "status": 400,
  "path": "/api/requests",
  "errors": [
    {
      "field": "departmentCode",
      "message": "departmentCode must be one of 50..99",
      "rejectedValue": "42"
    }
  ]
}

How Spring chooses which handler runs (internals, simplified)

When the validation exception is thrown, Spring consults HandlerExceptionResolvers. @RestControllerAdvice backed ExceptionHandlerExceptionResolver is consulted and, if a matching @ExceptionHandler exists, delegates to it. The handler returns a value or ResponseEntity, which Spring serializes to the HTTP response and ends processing.
If no handler is present, Spring's fallback resolvers generate a default 400 response with a framework defined body.

Conclusion

Walk through the article, we can see that validation is the first line of defense for any service. It protects business logic and persistence from malformed or malicious input, improves client experience with clear errors, and reduces debugging time for both providers and consumers. Placing validation at the boundary just after HTTP mapping but before controller logic lets you fail fast and keep deeper layers simple.

Hopefully the artical can help you to more get more understand about the validation workflow and helpful for developer career, thanks youuu... ☺️

DEV Community: Hai Nguyen

RESTful API: Why Is It Still the Standard for Web APIs?

What is RESTful API ?

To clarify:

Principle 1: Client–Server

Principle 2: Stateless

Principle 3: Cacheable

Principle 4: Uniform Interface

Principle 5: Layered System

Principle 6: Code on Demand (Optional)

Compare to other style of API

Final Thoughts

Validating REST API Requests in Spring Boot in practice

Why validation belongs at the API boundary

What happens when a request arrives (overview)

Common validation exceptions you should know

How validation failure is raised and routed (walkthrough)

Centralizing validation error handling recommended

Notes on the example handle

How Spring chooses which handler runs (internals, simplified)

Conclusion