Spring Boot REST API Cheat Sheet

This cheat sheet provides a quick reference for the most common annotations and classes used when building RESTful APIs with Spring Boot.

Class-Level Annotations

Annotation	Description
`@RestController`	A combination of `@Controller` and `@ResponseBody`. Marks a class as a request handler where every method returns a domain object instead of a view. It's the standard for building REST APIs.
`@RequestMapping("/api/v1")`	Maps a URL prefix to the entire controller. All method-level mappings in this class will be relative to this path.

Method-Level (Endpoint) Annotations

These annotations map specific HTTP methods and URL paths to your controller methods.

Annotation	Description
`@GetMapping("/users")`	Maps HTTP GET requests to the given URL. Used for retrieving resources.
`@PostMapping("/users")`	Maps HTTP POST requests. Used for creating new resources.
`@PutMapping("/users/{id}")`	Maps HTTP PUT requests. Used for updating/replacing an existing resource.
`@PatchMapping("/users/{id}")`	Maps HTTP PATCH requests. Used for partially updating an existing resource.
`@DeleteMapping("/users/{id}")`	Maps HTTP DELETE requests. Used for deleting a resource.

Parameter (Method Argument) Annotations

These annotations are used to extract data from the incoming HTTP request.

Annotation	Description	Example
`@PathVariable`	Binds a method parameter to a URI template variable.	`@GetMapping("/{id}")` `public User getUser(@PathVariable Long id)`
`@RequestParam`	Binds a method parameter to a URL query parameter.	`@GetMapping("/search")` `public List<User> search(@RequestParam String name)`
`@RequestBody`	Binds the body of the HTTP request to a method parameter. Spring automatically deserializes the JSON/XML in the request body into a Java object.	`@PostMapping("/")` `public User create(@RequestBody User newUser)`
`@RequestHeader`	Binds a method parameter to a request header.	`public void process(@RequestHeader("Content-Type") String contentType)`

Response Handling

Class / Annotation	Description
`@ResponseBody`	(Included in `@RestController`) Indicates that the return value of a method should be written directly to the HTTP response body. Spring's message converters will automatically serialize the object to JSON/XML.
`ResponseEntity<T>`	A powerful tool that represents the entire HTTP response. You can use it to control the status code, headers, and the response body. It provides fine-grained control over the response.

Example ResponseEntity Usage

Using ResponseEntity is the best practice for controlling the response status code.

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    // ... UserRepository injected here ...

    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        Optional<User> user = userRepository.findById(id);
        
        // Return 200 OK with the user, or 404 Not Found
        return user.map(ResponseEntity::ok)
                   .orElse(ResponseEntity.notFound().build());
    }

    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        User savedUser = userRepository.save(user);
        
        // Return 201 Created with the new user in the body
        return new ResponseEntity<>(savedUser, HttpStatus.CREATED);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userRepository.deleteById(id);
        
        // Return 204 No Content on successful deletion
        return ResponseEntity.noContent().build();
    }
}