Representational State Transfer (REST) is an architectural style for designing networked applications. RESTful APIs are web services that follow REST principles, allowing clients to interact with resources through a standardized set of HTTP methods. The main principles of RESTful APIs are:

In this post, I will show you how to create a simple RESTful API with Spring Boot, how to add validation for the API input, and finally, how to test. Let’s dive into it.

In a Spring Boot application, you can create RESTful APIs by defining controllers, routes, and handling HTTP requests. To do this, follow these steps.

Define a class and annotate it with @RestController. This tells Spring Boot that this class handles HTTP requests and generates responses.

Use the @RequestMapping annotation (or one of its shortcuts, like @GetMapping, @PostMapping, etc.) to map specific HTTP requests to your controller methods. Specify the HTTP method, the route path, and optionally, additional attributes like consumes or produces.

@GetMapping("/hello") public String hello() { return "Hello, World!"; }}

Your controller methods can accept parameters automatically populated by Spring Boot based on the incoming HTTP request. Use annotations like @PathVariable, @RequestParam, and @RequestBody to bind request data to your method parameters.

@PostMapping("/person") public Person createPerson(@RequestBody Person person) { // Handle the request and create a new person return person; }}

To demonstrate how to build a RESTful API with Spring Boot, let’s create a sample application for managing a list of persons. Using a simple in-memory data store, we’ll implement CRUD (Create, Read, Update, Delete) operations.

Define a simple Person class with a few fields (e.g., id, firstName, lastName).

// Getters and setters}

Define a PersonController class annotated with @RestController. Implement the CRUD operations by defining controller methods and using the appropriate HTTP methods and routes.

private final AtomicLong counter = new AtomicLong(); private final Map persons = new ConcurrentHashMap();

@PostMapping public Person createPerson(@RequestBody Person person) { long id = counter.incrementAndGet(); person.setId(id); persons.put(id, person); return person; }

@GetMapping("/{id}") public Person getPerson(@PathVariable("id") Long id) { return persons.get(id); }

@GetMapping public Collection getAllPersons() { return persons.values(); }

@PutMapping("/{id}") public Person updatePerson(@PathVariable("id") Long id, @RequestBody Person updatedPerson) { Person person = persons.get(id); if (person == null) { throw new ResourceNotFoundException("Person not found with id: " + id); } person.setFirstName(updatedPerson.getFirstName()); person.setLastName(updatedPerson.getLastName()); persons.put(id, person); return person; }

@DeleteMapping("/{id}") public void deletePerson(@PathVariable("id") Long id) { persons.remove(id); }}

In this example, we’ve created a PersonController class that manages a simple in-memory data store of Person objects. The controller provides CRUD operations through different HTTP methods and routes:

With this sample application, you’ve learned how to create a RESTful API with Spring Boot, define controllers, routes, and handle HTTP requests for various CRUD operations. You can now build on this foundation to create more complex APIs backed by real databases and integrate additional features like security, validation, and pagination.

To provide a robust and user-friendly API, it’s essential to validate user input and handle errors gracefully. In this section, we’ll show you how to add validation to your RESTful API using Spring Boot and handle any possible errors.

To add validation to your API, follow these steps

Annotate the fields in your model class (e.g., Person) with validation constraints from the javax.validation.constraints package. For example, use @NotNull, @Size, or @Pattern to specify constraints on your fields.

@NotNull(message = "First name must not be null") @Size(min = 1, max = 100, message = "First name must be between 1 and 100 characters") private String firstName;

@NotNull(message = "Last name must not be null") @Size(min = 1, max = 100, message = "Last name must be between 1 and 100 characters") private String lastName;

// Getters and setters}

Add the @Valid annotation to your controller method parameters to trigger validation when a request is received. If any validation errors are found, a MethodArgumentNotValidException is thrown.

To handle errors and provide custom error responses, follow these steps.

Define a class to represent your custom error response. This class will send a structured error message to the client when an error occurs.

// Getters and setters}

Create a class annotated with @ControllerAdvice to handle exceptions thrown by your controllers. Use the @ExceptionHandler annotation to define methods that handle specific exception types.

@ExceptionHandler(MethodArgumentNotValidException.class) public ResponseEntity handleValidationExceptions(MethodArgumentNotValidException ex) { List errors = ex.getBindingResult() .getAllErrors().stream() .map(ObjectError::getDefaultMessage) .collect(Collectors.toList());

ErrorResponse errorResponse = new ErrorResponse(); errorResponse.setStatus(HttpStatus.BAD_REQUEST.value()); errorResponse.setMessage("Validation error"); errorResponse.setErrors(errors);

return new ResponseEntity(errorResponse, HttpStatus.BAD_REQUEST); }

// Other exception handlers can be added here}

In this example, we handle the MethodArgumentNotValidException thrown when validation errors occur and return a custom error response with the validation error messages.

With these additions, your RESTful API now includes validation and error handling, making it more robust and user-friendly. You can expand on this foundation by adding more advanced features such as authentication, authorization, and rate limiting to ensure your API is secure and scalable.

Spring Boot Test is a powerful testing framework supporting various testing scenarios. Here’s how to write tests for your RESTful API.

Add the spring-boot-starter-test dependency to your project's pom.xml or build.gradle file.

Create test classes for your controllers and annotate them with @WebMvcTest. Use the @Autowired annotation to inject a MockMvc instance, which you can use to send HTTP requests and assert their responses.

@Autowired private MockMvc mockMvc;

// Test cases}

In your test cases, use the mockMvc.perform() method to send HTTP requests and the andExpect() method to assert the responses.

mockMvc.perform(get("/persons/1")) .andExpect(status().isOk()) .andExpect(jsonPath("$.firstName").value("John")) .andExpect(jsonPath("$.lastName").value("Doe"));}

In this example, we’ve written a test case for the getPerson() method in our PersonController. We send a GET request to the /persons/1 path, asserting that the response has a 200 OK status and the expected JSON content.

Spring Boot RESTful API. We introduced the basics of RESTful APIs, creating a simple API. Then, we delved into error handling and validation to enhance the API’s robustness. By following the examples and concepts presented in this blog post, you should now understand the fundamental principles and best practices for building a Spring Boot RESTful API.

As you continue to develop your API, you can explore additional Spring Boot features, such as securing, caching, asynchronous processing, and event-driven architectures, to further optimize and scale your application. With Spring Boot’s rich ecosystem and strong community support, there are endless possibilities for creating powerful, flexible, and maintainable APIs for your applications.

This post is created with the help of ChatGPT 4