Mastering HTTP: Requests, Responses, and Status Codes

Your learning outcome for this lesson:

Handle HTTP requests and responses, including returning appropriate status codes.

1. The Importance of HTTP Status Codes

Before we dive into the code, let's establish why this matters. HTTP status codes are a standardized way for a server to tell a client the outcome of its request. Using them correctly is fundamental to building predictable and reliable APIs.

While there are many status codes, they fall into five main categories:

• 1xx (Informational): Request received, continuing process. (Rarely used in APIs)
• 2xx (Successful): The request was successfully received, understood, and accepted.
• 3xx (Redirection): Further action needs to be taken to complete the request.
• 4xx (Client Error): The request contains bad syntax or cannot be fulfilled.
• 5xx (Server Error): The server failed to fulfill an apparently valid request.

For our rate limiter, and for most APIs, you'll frequently work with codes from the 2xx, 4xx, and 5xx series. One of the most important codes for our project will be 429 Too Many Requests.

2. Introducing ResponseEntity

In the previous lesson, you returned a Greeting object directly from your controller method. Spring's "magic" handled the rest. To gain full control, we use the ResponseEntity class.

ResponseEntity<T> is a generic class that represents the entire HTTP response. You can use it to specify:

• The status code (e.g., 200 OK, 404 Not Found).
• The response body (your data, which will be serialized to JSON).
• HTTP headers (which we'll explore later in the course, for example, to add a Retry-After header).

When Should You Use ResponseEntity?

It's tempting to use ResponseEntity for every method to be explicit, but that's not always necessary. The following video offers a great perspective on when to use it versus when a simpler return type is better.

The key takeaway is this: Use ResponseEntity when your method needs to dynamically change the response based on some logic. For example, if you need to return a 200 OK with data on success but a 404 Not Found if the data doesn't exist, ResponseEntity is the perfect tool.

3. Constructing Responses with ResponseEntity

ResponseEntity provides a flexible "builder" pattern that makes constructing responses clean and readable. You can chain method calls to build the exact response you need.

As you read, you'll see common static helper methods like:

• ResponseEntity.ok(body): For a 200 OK response.
• ResponseEntity.notFound().build(): For a 404 Not Found response with no body.
• ResponseEntity.badRequest().body(errorDetails): For a 400 Bad Request with an error message in the body.
• ResponseEntity.status(HttpStatus.CREATED).body(newItem): For a 201 Created response.

4. Practical Application: A Tour of Status Codes

Let's see how these are used in a typical CRUD (Create, Read, Update, Delete) application. The following video walks through implementing various status codes for different API operations. This will solidify your understanding of which status code to use in which scenario.

5. Exercise: Refactor Your GreetingController

Now, let's apply this to your own code. We'll refactor the GreetingController from the last lesson to use ResponseEntity and add some simple logic.

1. Modify the method signature: Change the return type of your greeting method from Greeting to ResponseEntity<Object>. We use Object as the generic type because we might return a Greeting on success or a String message on error.

2. Implement the logic: Add a check to see if the name parameter is blank.

   • If the name is valid, return a 200 OK with the Greeting object.
   • If the name is blank, return a 400 Bad Request with an error message.

Your updated GreetingController.java should look like this:

package com.example.ratelimiter.controller;

import com.example.ratelimiter.dto.Greeting;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.concurrent.atomic.AtomicLong;

@RestController
public class GreetingController {

    private static final String template = "Hello, %s!";
    private final AtomicLong counter = new AtomicLong();

    @GetMapping("/greeting")
    public ResponseEntity<Object> greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
        // Simple validation logic
        if (name == null || name.trim().isEmpty()) {
            return ResponseEntity
                    .status(HttpStatus.BAD_REQUEST)
                    .body("The 'name' parameter cannot be empty.");
        }

        // Success case
        Greeting body = new Greeting(counter.incrementAndGet(), String.format(template, name));
        return ResponseEntity.ok(body);
    }
}

Test your changes:

1. Run your application.
2. Navigate to http://localhost:8080/greeting?name=Student. You should see the familiar JSON success response and a 200 OK status in your browser's developer tools.
3. Now, navigate to http://localhost:8080/greeting?name=. You should see the error message "The 'name' parameter cannot be empty." and a 400 Bad Request status.

You have now successfully implemented dynamic response handling! In a future lesson, we'll see how to manage this kind of error handling more cleanly using a global exception handler, but this direct approach is perfect for understanding the core mechanics of ResponseEntity.

Key Takeaways

• ResponseEntity is the primary Spring class for gaining full control over an HTTP response, including the status code, body, and headers.
• Using standard HTTP status codes is essential for building clear and predictable APIs.
• The ResponseEntity builder pattern (.ok(), .status(), .body(), .build()) provides a clean and readable way to construct responses.
• You can dynamically return different responses from the same controller method based on your application's logic.
• Returning an HTTP 429 Too Many Requests is the standard way to signal that a rate limit has been enforced.

Next Steps

Now that you can create API endpoints and control their responses, the next step is to make your application's behavior configurable. Hardcoding values like "Hello, %s!" is fine for an example, but a real application needs flexibility.

In our next lesson, we will explore using Spring Boot's application.yml for basic application configuration. This will allow us to define settings outside of our Java code, a crucial step toward building the configurable rate limiter.