Managing HTTP Status Codes and API Versioning in Spring Boot

Course: Advanced Java Training

Topic: Managing HTTP Status Codes and API Versioning

Course Link: Advanced Java Training Course

Demo Link: Register for a Course Demo

Website: JustAcademy

1. Introduction

HTTP status codes and API versioning are important concepts in REST API development. HTTP status codes tell clients whether a request succeeded, failed, or requires additional action. API versioning allows developers to improve an API while maintaining compatibility for existing clients.

In Spring Boot, developers can manage HTTP responses using ResponseEntity, @ResponseStatus, exception handlers, and Spring MVC configuration. API versioning can be implemented through URL paths, request headers, query parameters, or media types.

Learning Objectives

• Understand the purpose and categories of HTTP status codes.
• Use appropriate status codes in Spring Boot REST controllers.
• Return status codes and response headers using ResponseEntity.
• Handle exceptions with consistent HTTP responses.
• Understand why API versioning is required.
• Implement URL-based, header-based, and query-parameter-based versioning.
• Design backward-compatible APIs and manage deprecated versions.
• Test status codes and versioned endpoints using Postman and curl.

2. What Are HTTP Status Codes?

An HTTP status code is a three-digit number returned by a server to indicate the outcome of an HTTP request. Clients use the code to decide whether to process the response, correct a request, authenticate, retry later, or handle an error.

For example, a successful GET request may return 200 OK, while a request for a nonexistent resource may return 404 Not Found.

2.1 Categories of HTTP Status Codes

3. Common HTTP Status Codes in REST APIs

3.1 Successful Response Codes

3.2 Client Error Codes

3.3 Server Error Codes

4. Why Correct HTTP Status Codes Matter

Returning the correct status code helps clients understand what happened without examining internal server details. It also improves API testing, monitoring, logging, debugging, and automated client behavior.

• Clear communication: Clients can distinguish successful operations from errors.
• Consistent integration: Frontend applications can handle API outcomes predictably.
• Better debugging: Developers can identify client-side and server-side failures.
• Reliable automation: Scripts and services can make decisions based on status codes.
• Correct caching behavior: Certain responses can be cached or revalidated according to HTTP semantics.
• Improved API documentation: Consumers know which outcomes to expect.

5. Managing HTTP Status Codes with ResponseEntity

ResponseEntity is a Spring class that lets a controller specify an HTTP status, response headers, and response body.

5.1 Returning 200 OK

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MessageController {

    @GetMapping("/api/message")
    public ResponseEntity<String> getMessage() {
        return ResponseEntity.ok("Request completed successfully");
    }
}

The endpoint returns status 200 OK and a response body containing the message.

5.2 Returning 201 Created

Use 201 Created when a request creates a new resource. If possible, include a Location header pointing to the newly created resource.

import java.net.URI;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ProductController {

    @PostMapping("/api/products")
    public ResponseEntity<Product> createProduct(
            @RequestBody Product product) {

        // In a real application, save the product
        // and obtain its actual generated ID.

        product.setId(101);

        URI location = URI.create("/api/products/101");

        return ResponseEntity.created(location)
                .body(product);
    }
}

This example illustrates the response structure. A production application should obtain the ID from the persistence layer instead of assigning a fixed value.

5.3 Returning 204 No Content

Use 204 No Content when an operation succeeds and no response body is needed, such as a successful deletion.

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.PathVariable;

@DeleteMapping("/api/products/{id}")
public ResponseEntity<Void> deleteProduct(
        @PathVariable int id) {

    // Delete the product using a service.
    return ResponseEntity.noContent().build();
}

5.4 Returning a Client Error

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;

public ResponseEntity<String> findProduct(int id) {
    if (id <= 0) {
        return ResponseEntity
                .badRequest()
                .body("Product ID must be positive");
    }

    return ResponseEntity.status(HttpStatus.NOT_FOUND)
            .body("Product was not found");
}

In an actual application, the controller should check whether the requested product exists before deciding whether to return 404 Not Found.

6. Using @ResponseStatus

The @ResponseStatus annotation assigns an HTTP status to a controller method or exception class. It is useful when a fixed status is sufficient and you do not need the flexibility of ResponseEntity.

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.PostMapping;

@RestController
public class RegistrationController {

    @PostMapping("/api/register")
    @ResponseStatus(HttpStatus.CREATED)
    public String register() {
        return "Registration completed";
    }
}

This method returns 201 Created. For APIs that create resources, consider returning a resource representation and a suitable Location header rather than only a message.

7. Handling Exceptions with HTTP Status Codes

Errors can occur when a resource does not exist, incoming data is invalid, or an unexpected server problem occurs. Instead of allowing uncontrolled exceptions to produce inconsistent responses, use explicit exception handling.

7.1 Creating a Custom Exception

public class ProductNotFoundException
        extends RuntimeException {

    public ProductNotFoundException(String message) {
        super(message);
    }
}

7.2 Handling the Exception Globally

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity<String> handleProductNotFound(
            ProductNotFoundException exception) {

        return ResponseEntity
                .status(HttpStatus.NOT_FOUND)
                .body(exception.getMessage());
    }
}

When a ProductNotFoundException is raised and not handled elsewhere, the global handler returns 404 Not Found.

7.3 Handling Invalid Request Bodies

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.HttpMessageNotReadableException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class RequestExceptionHandler {

    @ExceptionHandler(HttpMessageNotReadableException.class)
    public ResponseEntity<String> handleInvalidBody(
            HttpMessageNotReadableException exception) {

        return ResponseEntity
                .status(HttpStatus.BAD_REQUEST)
                .body("Invalid or unreadable request body");
    }
}

Spring MVC may raise HttpMessageNotReadableException when the request body cannot be parsed or converted into the required Java type. Avoid exposing stack traces or internal exception details in the response.

8. Creating a Consistent Error Response

A structured error response makes APIs easier to consume because clients receive predictable information about a failure.

8.1 Error Response DTO

public class ApiError {
    private int status;
    private String error;
    private String message;

    public ApiError() {
    }

    public ApiError(int status, String error, String message) {
        this.status = status;
        this.error = error;
        this.message = message;
    }

    public int getStatus() {
        return status;
    }

    public void setStatus(int status) {
        this.status = status;
    }

    public String getError() {
        return error;
    }

    public void setError(String error) {
        this.error = error;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

8.2 Returning the Structured Error

@ExceptionHandler(ProductNotFoundException.class)
public ResponseEntity<ApiError> handleNotFound(
        ProductNotFoundException exception) {

    ApiError error = new ApiError(
        404,
        "NOT_FOUND",
        exception.getMessage()
    );

    return ResponseEntity
            .status(HttpStatus.NOT_FOUND)
            .body(error);
}

Example response:

{
  "status": 404,
  "error": "NOT_FOUND",
  "message": "Product was not found"
}

For larger APIs, consider adopting a consistent error format such as Problem Details, supported in Spring through ProblemDetail in suitable framework versions. Keep error messages safe and avoid disclosing confidential system information.

9. What Is API Versioning?

API versioning is the practice of managing changes to an API by identifying different versions of its contract. It allows developers to add capabilities, modify response formats, or change behavior while giving existing clients a planned migration path.

For example, version 1 of a student API may return a student's full name in one field, while version 2 may return first name and last name separately. Keeping the versions distinct can prevent existing applications from breaking unexpectedly.

Why API Versioning Is Important

• Maintains compatibility for existing clients.
• Allows new features and response structures to be introduced.
• Supports gradual migration to newer API contracts.
• Reduces disruption when changes cannot remain backward-compatible.
• Allows documentation and testing to be maintained for each supported version.

10. When Should an API Be Versioned?

Not every change requires a new major API version. Backward-compatible additions may be introduced without creating a separate version, provided clients can safely tolerate the changes. Versioning is particularly important when changes can break existing consumers.

11. Common API Versioning Strategies

11.1 URL Path Versioning

URL path versioning includes the version number in the endpoint path.

GET /api/v1/students
GET /api/v2/students

Advantages:

• Easy to understand and test.
• Version is visible in logs, browser tools, and API documentation.
• Different versions can be routed to separate controller methods.

Disadvantages:

• Creates separate URL paths for different versions.
• Some API designs prefer to keep resource URLs independent of version identifiers.

11.2 Query Parameter Versioning

The version is provided as a query parameter.

GET /api/students?version=1
GET /api/students?version=2

Advantages: Easy to test and allows a version to be specified without changing the main path.

Disadvantages: Version handling must be clearly documented, and caches or intermediary systems must be configured to account for version-related query parameters.

11.3 Request Header Versioning

The client supplies the version in a custom HTTP header.

GET /api/students
API-Version: 1

Advantages:

• Keeps the resource path unchanged.
• Separates version selection from the URL.
• Supports APIs where the version is considered part of request metadata.

Disadvantages: Clients must set the header correctly, and documentation and cache behavior must account for it.

11.4 Media Type Versioning

The version can be represented through a media type parameter in the Accept header.

GET /api/students
Accept: application/vnd.justacademy.student-v2+json

This example uses a custom vendor media type. The server must explicitly support and document the media type and its version. If a client requests an unsupported representation, the API may return 406 Not Acceptable.

11.5 Comparison of Versioning Strategies

12. Implementing URL-Based API Versioning in Spring Boot

URL-based versioning is straightforward and commonly used in Spring Boot applications. Each version can have its own endpoint mapping and response DTO.

12.1 Version 1 Controller

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class StudentV1Controller {

    @GetMapping("/api/v1/students")
    public String getStudentsV1() {
        return """
            {
              "id": 101,
              "name": "Rahul Sharma"
            }
            """;
    }
}

This illustrative example returns a JSON-formatted string. For a production API, returning a DTO is preferable so Spring can serialize it and manage the response content type appropriately.

12.2 Version 2 Controller

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class StudentV2Controller {

    @GetMapping("/api/v2/students")
    public String getStudentsV2() {
        return """
            {
              "id": 101,
              "firstName": "Rahul",
              "lastName": "Sharma"
            }
            """;
    }
}

Version 1 returns a single name field, while version 2 splits the name into separate fields. Separate DTOs are generally recommended when the response contracts differ significantly.

12.3 Testing the Endpoints

GET http://localhost:8080/api/v1/students
GET http://localhost:8080/api/v2/students

Both routes can coexist while clients migrate. Maintain clear documentation explaining each version's request and response structure.

13. Using DTOs for Versioned Responses

Data Transfer Objects (DTOs) define the information an API accepts or returns. Separate DTOs can help keep version-specific contracts independent of database entities and internal application models.

13.1 Student Response for Version 1

public class StudentV1Response {
    private int id;
    private String name;

    public StudentV1Response() {
    }

    public StudentV1Response(int id, String name) {
        this.id = id;
        this.name = name;
    }

    public int getId() {
        return id;
    }

    public String getName() {
        return name;
    }
}

13.2 Student Response for Version 2

public class StudentV2Response {
    private int id;
    private String firstName;
    private String lastName;

    public StudentV2Response() {
    }

    public StudentV2Response(
            int id,
            String firstName,
            String lastName) {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
    }

    public int getId() {
        return id;
    }

    public String getFirstName() {
        return firstName;
    }

    public String getLastName() {
        return lastName;
    }
}

Using distinct DTOs lets each API version maintain its own response format while shared service logic handles common business operations.

14. Header-Based API Versioning

In header-based versioning, the client sends the version in a request header. One simple implementation reads the header and selects the appropriate response. This example demonstrates the concept without using Spring Framework 7's dedicated API versioning support.

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class VersionedStudentController {

    @GetMapping("/api/students")
    public ResponseEntity<?> getStudents(
            @RequestHeader(
                value = "API-Version",
                defaultValue = "1"
            ) String version) {

        if ("1".equals(version)) {
            return ResponseEntity.ok(
                new StudentV1Response(101, "Rahul Sharma")
            );
        }

        if ("2".equals(version)) {
            return ResponseEntity.ok(
                new StudentV2Response(101, "Rahul", "Sharma")
            );
        }

        return ResponseEntity
            .status(HttpStatus.BAD_REQUEST)
            .body("Unsupported API version");
    }
}

Send requests using:

GET /api/students
API-Version: 1

Or:

GET /api/students
API-Version: 2

This simplified implementation defaults to version 1 when the header is absent. A production API should document that behavior, validate versions consistently, and use an appropriate error response for unsupported versions.

15. Query Parameter API Versioning

Query parameter versioning can be implemented by accepting a query parameter and selecting the appropriate DTO.

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;

@RestController
public class StudentQueryVersionController {

    @GetMapping("/api/students")
    public ResponseEntity<?> getStudents(
            @RequestParam(defaultValue = "1") int version) {

        if (version == 1) {
            return ResponseEntity.ok(
                new StudentV1Response(101, "Rahul Sharma")
            );
        }

        if (version == 2) {
            return ResponseEntity.ok(
                new StudentV2Response(101, "Rahul", "Sharma")
            );
        }

        return ResponseEntity
            .status(HttpStatus.BAD_REQUEST)
            .body("Unsupported API version");
    }
}

Example requests:

GET /api/students?version=1
GET /api/students?version=2

In this implementation, a missing version defaults to 1. An invalid non-numeric value may be rejected by Spring during parameter conversion, typically with a 400 Bad Request response.

16. API Versioning Support in Spring Framework 7

Spring Framework 7 introduces built-in API versioning support for Spring MVC and WebFlux. This is different from manually checking a header or query parameter inside a controller. The framework can resolve and validate the requested version and select an appropriately versioned handler.

For example, a Spring Boot application using a compatible Spring Framework 7 release can configure header-based versioning using the supported MVC properties:

spring.mvc.apiversion.use.header=API-Version

A controller can then declare a version on a mapping:

@RestController
public class AccountController {

    @GetMapping(path = "/api/accounts/{id}", version = "1.0")
    public Account getAccountV1() {
        // Return the version 1 representation.
        return new Account();
    }
}

Compatibility note: The version mapping attribute and the property shown above require compatible Spring Framework 7 and Spring Boot support. They are not available in the same form in many Spring Boot 3 projects. Check your application's framework version and reference documentation before using them. The manual URL, header, and query parameter examples earlier in these notes illustrate approaches that can also be implemented in older Spring Boot versions.

17. Backward Compatibility in API Design

Backward compatibility means that existing clients can continue to use an API after changes are introduced. A compatible change should not unexpectedly break previously valid requests or responses.

Recommended Practices

• Add optional response properties when clients can safely tolerate additional fields.
• Avoid removing or renaming fields that existing clients rely on.
• Avoid changing a property's data type without an appropriate migration plan.
• Document required request fields and validation rules.
• Use DTOs to keep public API contracts separate from internal entities.
• Maintain automated contract and integration tests.
• Communicate breaking changes before releasing a new major version.
• Provide a migration guide and a realistic deprecation period.

18. Deprecating an Old API Version

Deprecation indicates that an API version is scheduled to be phased out or should no longer be used for new integrations. Deprecation should be communicated clearly, with enough time for clients to migrate.

Recommended Deprecation Process

1. Identify the version that will be deprecated.
2. Publish the replacement version and migration documentation.
3. Notify API consumers through appropriate communication channels.
4. Where appropriate, return deprecation information through response headers or API documentation.
5. Monitor traffic to identify clients that still use the old version.
6. Announce the retirement date in advance.
7. Retire the version according to the published migration policy.

HTTP headers such as Deprecation, Sunset, and Link can help communicate lifecycle information when implemented according to the relevant specifications and documented API policy. These headers do not automatically retire an endpoint; the server and its owners must manage the lifecycle.

19. Choosing the Right Versioning Strategy

There is no single versioning strategy that is ideal for every application. The decision depends on client requirements, caching behavior, infrastructure, API governance, and how versions are documented.

Choose one primary approach for an API unless there is a clear reason to support multiple mechanisms. Consistency reduces confusion for clients and developers.

20. Testing HTTP Status Codes and API Versions

Testing confirms that endpoints return the expected status codes and that each API version follows its documented contract.

20.1 Testing with curl

Test a versioned endpoint using URL-based versioning:

curl -i http://localhost:8080/api/v1/students

Test the second version:

curl -i http://localhost:8080/api/v2/students

Test header-based versioning:

curl -i \
  -H "API-Version: 2" \
  http://localhost:8080/api/students

20.2 Testing with Postman

1. Open Postman and create a request.
2. Select the appropriate HTTP method.
3. Enter the API endpoint URL.
4. Add required headers such as API-Version or Accept.
5. Send the request.
6. Verify the HTTP status code, response body, and response headers.
7. Repeat with valid, invalid, missing, and unsupported version values.

20.3 Important Test Cases

• Successful request returns the expected success status.
• Missing resource returns 404 Not Found.
• Malformed input returns an appropriate client error.
• Unsupported API versions are handled according to the documented policy.
• Each supported version returns the correct DTO structure.
• Authentication and authorization requirements remain consistent with the API contract.
• Deprecated versions provide the documented migration information.

21. Common Mistakes and Troubleshooting

22. Best Practices

• Use HTTP status codes according to their defined semantics.
• Return 201 Created when a resource is created and include a Location header when appropriate.
• Return 204 No Content only when no response body is needed.
• Use 400 Bad Request for malformed requests and suitable validation errors.
• Use 401 for missing or invalid authentication and 403 when access is forbidden.
• Use 404 Not Found when the requested resource cannot be found.
• Centralize exception handling using @RestControllerAdvice where suitable.
• Use structured error responses with stable fields.
• Document every supported API version and its behavior.
• Prefer backward-compatible changes whenever practical.
• Use separate DTOs when versions have different request or response contracts.
• Test both successful and failed scenarios.
• Plan deprecation and retirement before removing an old API version.

23. Practical Exercise

Exercise: Build a versioned Student Management REST API in Spring Boot.

Requirements

1. Create two response DTOs: StudentV1Response and StudentV2Response.
2. Implement /api/v1/students and /api/v2/students.
3. Return 200 OK for successful retrieval.
4. Return 201 Created when a student is created.
5. Return 404 Not Found when a requested student does not exist.
6. Implement consistent exception handling with @RestControllerAdvice.
7. Optionally implement header-based version selection.
8. Test supported and unsupported versions in Postman.
9. Write tests that verify both status codes and response structures.
10. Document how clients can migrate from version 1 to version 2.

Expected Outcome

The application should return appropriate HTTP status codes, expose separate API response contracts, handle errors consistently, and allow clients to use the documented versions without unexpected breaking changes.

24. Interview Questions and Answers

Q1. What is an HTTP status code?

Answer: It is a three-digit code in an HTTP response that indicates the outcome of a request.

Q2. What is the difference between 200 OK and 201 Created?

Answer: 200 indicates that a request succeeded. 201 indicates that the request resulted in the creation of a resource.

Q3. When should 204 No Content be used?

Answer: When the request succeeds and the server has no response body to return.

Q4. What is the difference between 401 and 403?

Answer: 401 indicates that valid authentication credentials are missing or unavailable. 403 indicates that the server refuses the request, typically because the client lacks permission.

Q5. What is ResponseEntity?

Answer: ResponseEntity is a Spring abstraction that allows a controller to define an HTTP response's status, headers, and body.

Q6. What is @ResponseStatus?

Answer: It declares an HTTP status for a controller method or exception class.

Q7. What is API versioning?

Answer: API versioning manages changes to an API contract so different clients can use supported versions while developers evolve the service.

Q8. Why is API versioning necessary?

Answer: It helps introduce breaking changes without unexpectedly disrupting existing clients.

Q9. What are the common API versioning strategies?

Answer: URL path, query parameter, request header, and media type versioning are common approaches.

Q10. What is URL-based versioning?

Answer: It places the version in the endpoint path, for example /api/v1/students.

Q11. What is header-based versioning?

Answer: It identifies the requested version through an HTTP request header, such as API-Version: 2.

Q12. What is backward compatibility?

Answer: It means existing clients continue to work when an API is updated, without being forced to adopt breaking changes immediately.

Q13. Why use DTOs for API versioning?

Answer: DTOs separate public request and response formats from internal entities and allow different versions to maintain different contracts.

Q14. How can Spring Boot handle exceptions globally?

Answer: Use @RestControllerAdvice with @ExceptionHandler methods to map exceptions to consistent response statuses and bodies.

Q15. What is API deprecation?

Answer: Deprecation communicates that a version is being phased out and that clients should migrate to a supported alternative.

Q16. Does every API change require a new version?

Answer: No. Backward-compatible changes may not require a new major version. Changes that break existing client expectations usually require a carefully managed migration strategy.

25. Quick Revision Checklist

• Understand the five HTTP status code categories.
• Use success codes for successful operations and error codes for failures.
• Use ResponseEntity when controlling status, headers, and body.
• Use @ResponseStatus for fixed status declarations.
• Centralize exception handling when appropriate.
• Use structured error responses.
• Understand URL, query parameter, header, and media type versioning.
• Use DTOs to isolate version-specific response structures.
• Preserve backward compatibility where possible.
• Document and test all supported versions.
• Communicate deprecation and migration timelines clearly.

26. Conclusion

Managing HTTP status codes and API versioning is essential for building predictable, reliable, and maintainable Spring Boot REST APIs. Correct status codes help clients understand request outcomes, while consistent exception handling ensures that errors are communicated safely and clearly.

API versioning enables an application to evolve without unnecessarily breaking existing integrations. By choosing a suitable versioning strategy, using version-specific DTOs, maintaining backward compatibility, and testing each contract, developers can create APIs that are easier to maintain and integrate with.

To continue learning Java and Spring Boot, explore the Advanced Java Training Course, visit the JustAcademy website, or register for a course demo.