Mastering HTTP Methods in Spring Boot 3: A Complete Guide to RESTful APIs

1. Introduction

RESTful APIs are the standard for building efficient, scalable, and maintainable services. This article explains how to use various HTTP methods (GET, POST, PUT, DELETE, PATCH, HEAD) in Spring Boot 3.2.5 to design high‑quality APIs, covering endpoint definition, controller implementation, response handling, and the importance of proper HTTP status codes.

2. HTTP Methods

2.1 GET

GET retrieves a resource representation and is idempotent. In Spring Boot, use @GetMapping on a controller method, returning the resource directly or wrapped in ResponseEntity . Best practices include using nouns in URIs, keeping endpoints simple, supporting pagination, filtering, sorting, setting appropriate Cache‑Control headers, and versioning APIs.

2.2 HEAD

HEAD returns only the response headers (metadata) without a body, useful for checking resource existence, reducing bandwidth, and achieving faster responses. Implement it with @RequestMapping(method = RequestMethod.HEAD) or a dedicated @HeadMapping if available.

2.3 DELETE

DELETE removes a specific resource identified by its URI and is idempotent. Define the endpoint with @DeleteMapping , ensure proper authorization, handle errors, log the operation, and return status 204 No Content on success.

2.4 PUT

PUT creates or fully updates a resource and is idempotent. Use @PutMapping , provide the complete resource representation in the request body, validate input, support pagination, and return 200 OK or 201 Created as appropriate.

2.5 POST

POST creates a new resource and is non‑idempotent. Define it with @PostMapping , let the server generate the resource URI, validate the request body, handle errors, and return 201 Created with a Location header.

2.6 PATCH

PATCH performs partial updates. Use @PatchMapping , send only the fields to modify, consider versioning with ETag/If‑Match for conditional updates, and return appropriate success or error codes.

3. HTTP Status Codes

Spring Boot controllers should return the correct HTTP status codes to convey the result of a request. Common codes include 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, and 500 Internal Server Error.