HTTP Status Codes & Methods in REST API with Spring Boot & Spring MVC

1. Introduction

In RESTful services, HTTP status codes and methods play a crucial role in determining the success or failure of requests. Understanding how to use these correctly helps in building robust APIs. In this post, we’ll look at common HTTP status codes (200, 400, 401) and HTTP methods (GET, POST, PUT, DELETE) in the context of Spring Boot and Spring MVC, with real-time use cases for employee management, gaming, teaching, and food order payments.
 

2. HTTP Status Codes

2.1. HTTP 200 – OK

The HTTP 200 status code indicates a successful request. It’s the standard response for successful GET, POST, PUT, and DELETE requests.

Use Case: Employee Management

In an employee management system, after adding or updating an employee, a response with a 200 OK status is sent to confirm that the request was successfully processed.

Sample Code

2.2. HTTP 400 – Bad Request

The HTTP 400 status code indicates that the server could not process the request due to client-side errors, such as invalid data or missing parameters.

Use Case: Gaming

In a gaming API, if a player sends an invalid move (e.g., a non-existent character ID), the server responds with a 400 Bad Request status.

Sample Code

2.3. HTTP 401 – Unauthorized

HTTP 401 status code means the client is unauthorized to access the requested resource, typically due to missing or invalid authentication.

Use Case: Teaching Platform

In a teaching platform API, a teacher or student attempting to access resources without being logged in would get a 401 Unauthorized status.

Sample Code

3. HTTP Methods

3.1. GET

The GET method retrieves data from the server.

Use Case: Food Order System

In a food order system, retrieving a list of menu items using a GET request.

Sample Code

3.2. POST

The POST method is used to send data to the server, such as creating a new record.

Use Case: Employee Management

Creating a new employee record.

Sample Code

3.3. PUT

The PUT method is used to update an existing resource.

Use Case: Gaming

Updating a player’s status in a game.

Sample Code

3.4. DELETE

The DELETE method is used to remove a resource from the server.

Use Case: Food Order System

Deleting an item from a customer’s food order.

Sample Code

5. HTTP 201 – Created

The HTTP 201 status code indicates that a request has been successfully processed and resulted in the creation of a new resource.

Use Case: Employee Management

When an employee is successfully created, return a 201 Created status.

Sample Code

6. HTTP 202 – Accepted

The HTTP 202 status code indicates that the request has been accepted for processing, but the processing has not been completed.

Use Case: Gaming

When a game action is initiated, but not completed yet (e.g., a server-side action like saving game progress), return HTTP 202.

Sample Code

7.HTTP 203 – Non-Authoritative Information

The HTTP 203 status code indicates that the response metadata is not from the origin server but from a local or third-party copy.

Use Case: Teaching Platform

In an online teaching platform, if course data is fetched from a cached version, this status code may be used.

Sample Code

8.HTTP 204 – No Content

The HTTP 204 status code indicates that the request has been successfully processed, but there is no content to return.

Use Case: Food Order System

When a food order is successfully updated (e.g., a customer changes their delivery address), return HTTP 204 No Content.

Sample Code

9. HTTP 301 – Moved Permanently

The HTTP 301 status code indicates that the resource requested has been permanently moved to a new location.

Use Case: Food Order System

If a food delivery address API has moved to a new endpoint, this status code is returned.

Sample Code

10.HTTP 302 – Found (Temporary Redirect)

The HTTP 302 status code indicates that the resource is temporarily located at a different URI.

Use Case: Gaming

If a player's request is temporarily redirected to a new game server for load balancing.

Sample Code

11.HTTP 400 – Bad Request

This indicates that the request could not be understood or was missing required parameters.

Use Case: Food Order System

If a customer places an incomplete order (missing item details), return HTTP 400.

Sample Code

12. HTTP 401 – Unauthorized

This status indicates that the request lacks valid authentication credentials.

Use Case: Teaching Platform

A student or teacher attempting to access course content without being logged in should receive this status.

Sample Code

13. HTTP 402 – Payment Required

This status code is not widely used, but it could indicate that payment is required to proceed with the request.

Use Case: Food Order Payment

In a food ordering system, the user is asked to pay before placing an order.

Sample Code

14. HTTP 403 – Forbidden

This status indicates that the server understands the request but refuses to authorize it.

Use Case: Teaching Platform

If a user tries to access restricted courses they don't have permission for, return HTTP 403.

Sample Code

15. HTTP 404 – Not Found

This status indicates that the requested resource could not be found.

Use Case: Employee Management

When an employee with a specific ID does not exist in the system.

Sample Code

16. HTTP 500 – Internal Server Error

This indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.

Use Case: Gaming

When there’s an unexpected error in the game server (e.g., database failure).

Sample Code

17. HTTP 502 – Bad Gateway

This status code indicates that the server received an invalid response from the upstream server.

Use Case: Food Order Payment

If a food payment gateway returns an error, a 502 Bad Gateway status could be returned.

Sample Code

@RequestParam vs @QueryParam vs @PathVariable vs @PathParam

Here's a comparison of the four annotations commonly used in Spring and JAX-RS (Java API for RESTful Web Services) for extracting parameters from a request:

1. @RequestParam (Spring Framework):

   • Used to extract query parameters or form parameters from the request URL in Spring MVC or Spring Boot.

   • Typically used for GET requests with URL parameters or form submissions.

     

     2. @QueryParam (JAX-RS):

   • Similar to @RequestParam in Spring but used in JAX-RS (used in frameworks like Jersey or RESTEasy).
   • Extracts query parameters from the URL, typically used with HTTP GET.

   

   URL: /employees?department=HR

   3. @PathVariable (Spring Framework):

   Used to extract variables from the URI path, typically used with RESTful endpoints where the parameter is part of the URL path.

   Commonly used with dynamic URIs like /employees/{id}.

   

   4. @PathParam (JAX-RS):

   Similar to @PathVariable in Spring but used in JAX-RS.

   Extracts parameters from the URI path.

   

    

   

    

2. Feature	@RequestParam (Spring)	@QueryParam (JAX-RS)	@PathVariable (Spring)	@PathParam (JAX-RS)
   Framework	Spring MVC / Spring Boot	JAX-RS (Jersey, RESTEasy, etc.)	Spring MVC / Spring Boot	JAX-RS (Jersey, RESTEasy, etc.)
   Usage	Used to extract query parameters or form data from the URL or body	Extracts query parameters from the URL	Extracts values from the path of the URL	Extracts values from the path of the URL
   HTTP Methods	Typically used in GET, POST, PUT, DELETE (for query/form data)	Typically used in GET, POST, PUT, DELETE (for query data)	Typically used in GET, POST, PUT, DELETE (for dynamic path segments)	Typically used in GET, POST, PUT, DELETE (for dynamic path segments)
   Type of Parameter	Query parameters or form parameters	Query parameters	Path parameters (part of the URL)	Path parameters (part of the URL)
   Example URL	/employees?department=HR	/employees?department=HR	/employees/123	/employees/123
   Method Example	public List<Employee> getEmployees(@RequestParam String department)	public List<Employee> getEmployees(@QueryParam("department") String department)	public Employee getEmployeeById(@PathVariable Long id)	public Employee getEmployeeById(@PathParam("id") Long id)
   Annotation Placement	Can be used with method parameters in controller classes	Can be used with method parameters in JAX-RS resource classes	Can be used with method parameters in controller classes	Can be used with method parameters in JAX-RS resource classes
   Default Value Support	Supports default values using defaultValue attribute	Supports default values using defaultValue attribute	Does not support default values	Does not support default values
   Required/Optional	Default is required, but can be made optional using required = false	Default is required, but can be made optional using defaultValue	Always required if the path is dynamic	Always required if the path is dynamic
   Common Use Case	For handling form data or query parameters like search filters or pagination	For handling query parameters in RESTful web services	For handling resource identifiers in RESTful web services	For handling resource identifiers in RESTful web services

3. Summary of Use Cases:

   @RequestParam / @QueryParam: Extract query parameters, often for filters, search criteria, or form data (e.g., ?page=1&size=10).

   @PathVariable / @PathParam: Extract path parameters, commonly used for dynamic resource identifiers (e.g., /employees/{id}).