Creating REST Controllers & API Endpoints

Table of Contents

1. Introduction
2. What is a RESTful Web Service?
3. Spring MVC for RESTful APIs
4. Creating a REST Controller
5. Mapping HTTP Methods to Controller Methods
6. Request and Response Handling
7. Consuming JSON and Producing Responses
8. Using Path Variables and Query Parameters
9. Handling Errors and Exceptions in REST APIs
10. Best Practices for RESTful APIs
11. Conclusion

1. Introduction

In this module, we will explore how to create RESTful APIs in a Spring Boot application using Spring MVC. REST (Representational State Transfer) is an architectural style for designing networked applications, and it is commonly used for building scalable and flexible web services. Spring MVC, with its @RestController annotation, makes it simple to develop RESTful web services.

We will walk through the steps of setting up a basic REST controller, defining API endpoints, handling request data, and formatting responses in JSON, which is the standard data format for REST APIs.

2. What is a RESTful Web Service?

A RESTful web service is a service that adheres to the principles of REST and allows interaction with web services through stateless communication. RESTful APIs expose a set of HTTP endpoints that clients can interact with using standard HTTP methods such as GET, POST, PUT, and DELETE.

Key principles of REST include:

• Stateless: Each request from the client contains all the necessary information to process the request.
• Resource-Based: Resources (data) are identified using URLs (Uniform Resource Identifiers).
• HTTP Methods: REST APIs use HTTP methods (GET, POST, PUT, DELETE) to perform operations on resources.
• Representation: Resources are represented as documents (usually in JSON or XML format).

3. Spring MVC for RESTful APIs

Spring MVC provides an easy way to build RESTful APIs. With the @RestController annotation, Spring automatically serializes and deserializes data between Java objects and JSON or XML formats. Spring also provides annotations like @RequestMapping, @GetMapping, @PostMapping, etc., to define the API endpoints and HTTP methods.

Spring Boot, a module of the Spring Framework, simplifies setting up Spring MVC applications by providing defaults and automatic configurations, making it easier to create RESTful web services.

4. Creating a REST Controller

To create a REST API in Spring, the first step is to define a controller using the @RestController annotation. This annotation indicates that the class will handle HTTP requests and return responses as JSON or XML.

Here’s an example of a basic RestController in Spring Boot:

javaCopyEdit@RestController
@RequestMapping("/api")
public class GreetingController {

    @GetMapping("/greet")
    public String greet() {
        return "Hello, welcome to the REST API!";
    }
}

• @RestController: This annotation is a specialization of the @Controller annotation that combines @Controller and @ResponseBody. It indicates that the methods in this class will return data directly, bypassing the need for a view (like JSP or Thymeleaf).
• @RequestMapping("/api"): Specifies the base URL path for all methods in this controller.
• @GetMapping("/greet"): Maps the HTTP GET request to the greet() method.

5. Mapping HTTP Methods to Controller Methods

Spring MVC provides specific annotations to map different HTTP methods to controller methods. The most commonly used ones are:

• @GetMapping: Maps HTTP GET requests to a method.
• @PostMapping: Maps HTTP POST requests to a method.
• @PutMapping: Maps HTTP PUT requests to a method.
• @DeleteMapping: Maps HTTP DELETE requests to a method.
• @PatchMapping: Maps HTTP PATCH requests to a method.

Example:

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

    // Handle GET request to retrieve all users
    @GetMapping
    public List<User> getAllUsers() {
        return userService.getAllUsers();
    }

    // Handle POST request to create a new user
    @PostMapping
    public User createUser(@RequestBody User user) {
        return userService.createUser(user);
    }

    // Handle PUT request to update an existing user
    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody User user) {
        return userService.updateUser(id, user);
    }

    // Handle DELETE request to delete a user
    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) {
        userService.deleteUser(id);
    }
}

In the above example:

• @GetMapping is used to handle GET requests, returning a list of all users.
• @PostMapping is used to handle POST requests for creating new users.
• @PutMapping is used to handle PUT requests for updating existing users.
• @DeleteMapping is used to handle DELETE requests for deleting users.

6. Request and Response Handling

Request Handling

In Spring MVC, you can handle request data in several ways:

• Path Variables: Extract dynamic data from the URL.
• Request Parameters: Retrieve query parameters from the URL.
• Request Body: Extract the request body (e.g., JSON) and map it to Java objects using @RequestBody.

Path Variables:

javaCopyEdit@GetMapping("/user/{id}")
public User getUser(@PathVariable Long id) {
    return userService.getUser(id);
}

Request Parameters:

javaCopyEdit@GetMapping("/search")
public List<User> searchUsers(@RequestParam String name) {
    return userService.searchUsers(name);
}

Request Body:

javaCopyEdit@PostMapping("/user")
public User createUser(@RequestBody User user) {
    return userService.createUser(user);
}

Response Handling

In Spring MVC, the response can be returned in various formats, typically as JSON or XML. Spring automatically handles the conversion between Java objects and JSON using the Jackson library (by default).

Response Entity:

To customize the HTTP response, such as setting status codes or headers, you can use ResponseEntity:

javaCopyEdit@GetMapping("/user/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    User user = userService.getUser(id);
    if (user == null) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
    }
    return ResponseEntity.ok(user);
}

In this example:

• ResponseEntity.ok(): Returns a response with HTTP status 200 (OK).
• ResponseEntity.status(): Allows setting custom status codes.

7. Consuming JSON and Producing Responses

When building RESTful APIs, it is essential to consume and produce data in JSON format. Spring automatically handles the serialization and deserialization of Java objects to and from JSON.

Producing JSON Response:

javaCopyEdit@GetMapping("/user/{id}")
public User getUser(@PathVariable Long id) {
    return userService.getUser(id); // Automatically converted to JSON
}

Consuming JSON Request Body:

javaCopyEdit@PostMapping("/user")
public User createUser(@RequestBody User user) {
    return userService.createUser(user); // Automatically deserialized from JSON
}

8. Using Path Variables and Query Parameters

Spring MVC allows easy extraction of path variables and query parameters from the HTTP request. You can use the @PathVariable and @RequestParam annotations to access these parameters.

Path Variables:

javaCopyEdit@GetMapping("/user/{id}")
public User getUser(@PathVariable Long id) {
    return userService.getUser(id);
}

Query Parameters:

javaCopyEdit@GetMapping("/search")
public List<User> searchUsers(@RequestParam String name) {
    return userService.searchUsers(name);
}

9. Handling Errors and Exceptions in REST APIs

In RESTful APIs, proper error handling is essential for providing useful feedback to clients. Spring provides a @ControllerAdvice annotation that can be used to handle exceptions globally.

javaCopyEdit@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<String> handleResourceNotFound(ResourceNotFoundException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }
}

In this example:

• @ExceptionHandler is used to handle specific exceptions (e.g., ResourceNotFoundException).
• ResponseEntity allows you to send a custom error message along with an HTTP status code.

10. Best Practices for RESTful APIs

• Use HTTP Methods Correctly: Use GET for retrieving resources, POST for creating, PUT for updating, and DELETE for deleting.
• Use Meaningful HTTP Status Codes: Return appropriate status codes like 200 (OK), 201 (Created), 400 (Bad Request), 404 (Not Found), and 500 (Internal Server Error).
• Use Consistent Naming Conventions: Use plural nouns for resources (e.g., /users, /products) and maintain consistency in URL paths.
• Version Your API: Use versioning in the URL (e.g., /api/v1/users) to ensure backward compatibility.

11. Conclusion

In this module, we’ve learned how to create RESTful web services in Spring Boot using Spring MVC. We covered creating REST controllers, mapping HTTP methods to controller methods, handling requests and responses, using path variables and query parameters, and handling errors in a RESTful way.