Spring Boot: Apprentice Cookbook
Spring Boot is a web framework built on top of the framework Spring. It is designed for easier use and quicker implementation. It does so by configuring the application and its environment as automatically as possible. As a newcomer, I can say that it makes the framework really easy to get into.
My learning led me to read most of the reference documentation, which is well written and gives you a lot of insights into the internal behavior of Spring Boot. This documentation gives a lot of details, so this article aims to take the counter approach and pinpoint the concepts you will need to implement an API using Spring Boot. I will complement each section with a set of links to related documentation, may you want to dig further.
As a side note, this document will be using version 2.4.2 of the framework, on a Java project using Gradle as the build system. However, the information remains applicable to any compatible language and build system.
This article will cover the following aspects of creating an API with Spring Boot:
- Bootstrap the project
- Create REST endpoints
- Handle errors
- Connect to a persistence layer
- Paginate the results
- Test the application
- Package the Application
Bootstrap the project
This part may be the easiest, as Spring Boot is providing a package generator at https://start.spring.io/. We can select all required modules and retrieve an archived project with the build system, dependencies, and main application class.
Outside of this generator, to declare a RESTful API, our project should define the Spring Boot starter web dependency. The starter dependencies are a set of ready to use features packaged by Spring Boot.
The application’s main method should be contained in any class, on which we should apply the annotation @SpringBootApplication. This annotation is responsible for a lot of automatic configurations, namely the components injection and web server startup.
Starting the server is as simple as using the embedded command ./gradlew bootRun. The server will start, but we don’t have any endpoint to serve at the moment.
Documentation links:
Create a REST endpoint
To create a controller, we simply have to annotate any class with @RestController. We can then configure any method inside this controller as an endpoint using @RequestMapping.
@RequestMapping help us configuring the endpoint by providing an URL, the HTTP verb, the expected data type, and more. It can be applied both on a class and a method, the configurations applied on the class will be inherited by the methods underneath and the path concatenated.
To control our endpoint status codes we will return aResponseEntity, holding both the response message and HttpStatus.
The ResponseEntity will be automatically transformed to an HTTP response, using the HttpStatus as response code and transforming the message to a JSON object. On top of transforming Maps to JSON objects, Spring Boot configure Jackson to map all public attributes or getters of any class to a JSON object.
Documentation links:
Advanced endpoint configuration
Now that we have a controller, we may want to define dynamic HTTP endpoints. To do so, the main annotations to keep in mind are:
@RequestBody: Defines a body structure through a java Class.@PathVariable: Defines a variable subpart of the endpoint URL.@RequestParam: Defines a query parameter.
The controller below showcases the three annotations with two endpoints, each returning a custom “Hello World” depending on the query.
The endpoints defined above can be used as follow:
Documentation links:
Handle errors
By default, Spring Boot will return the HTTP code 200 for any successful request, 404 if the endpoint is not registered, and 500 for any error. We already saw that using ResponseEntity enables us to override this behavior for successful requests, but we still need to handle error codes more finely.
To do so, we will define custom API exceptions that will be automatically transformed into HTTP codes. This transformation is done by a class extending ResponseEntityExceptionHandler and annotated with @ControllerAdvice. In this class, we can define methods to handle exceptions using the annotations @ExceptionHandler and @ResponseStatus.
After defining the ControllerAdvice in your project, any exception thrown by your controllers will be parsed and transformed to the bound ResponseStatus.
Our exception handling is very simple and does not return any payload, but it is possible to implement exception parsing in the methods of ResponseEntityExceptionHandler.
Documentation links:
Connect to a persistence layer
Configuration
To use a database, we will need the Java Persistence API (JPA) package and the implementation of any persistence layer. The former will install interface APIs, while the latter will provide the implementations and drivers.
To pinpoint the minimal changes required to switch between two distinct databases, we will show the integration with both PostgreSQL and H2 at the same time. First, let’s declare our dependencies:
The second step is to configure the accesses in application.properties. The property file is the first and the last time we will have to worry about our persistence configuration. In this file, the 3 lines commented out are the only part to change to switch from PostgreSQL to H2.
Documentation links:
Define a model
Defining a model is as simple as using annotations defined on JSR-317. These annotations are available through the package javax.persistence, which is available through the JPA dependency.
For instance, the code below creates a Delivery entity. Our entity identifier is the field id, which will be automatically initialized and increased on each new saved entity in the database thanks to the annotation @GeneratedValue.
Note: All attributes publicly available will be set into the JSON representation of the entity in the API responses.
To ensure consistency of our data class, we applied @NotNull validations from JSR-303, these validations can be enforced on endpoints as we will see during the next section. The constraints are contained in the package javax.validation.constraints, available through the dependency spring-boot-starter-validation.
Documentation links:
javax.persistence API documentation (@Entity, @Column, @Enumerate, …)
Expose the model
To interact with our models, we have to define a Repository, for instance, a CrudRepository. Doing so is as easy as extending the class with an empty class. Spring Boot will automatically implement functions to interact with the entity.
We annotate this component @Repository to make it available to dependency injection. Then we can inject and use the repository in any class, for example directly in a controller. Using@Autowired will automatically retrieve the @Repository declared above.
Note: @Repository and @Service behave exactly as the main injection annotation@Component, it simply enables to mark a semantic difference.
We used the annotation@Valid to ensure that our constraints defined above are met on the sent Delivery body.
Note: H2 is an in-memory database so the data will be wiped out at each server restart.
Documentation Links:
Paginate the results
This section illustrates how well Spring Boot integrates some classic features of a web API. To paginate the access to our previous entity Delivery, we simply have to change the repository’s extended class from CrudRepository to PagingAndSortingRepository.
This repository implementation provides a new method findAll(Pageable) returning a Page. The class Pageable configures the page and page size to return.
The endpoint will then serve the whole Page object’s data upon request.
Documentation links:
Test the application
Spring Boot provides every tool to easily test controllers with a set of APIs and mocks. Mostly, MockMvc will enable us to send requests and assert response content without having to worry about technicalities.
As an example, we are testing the POST endpoint from the section above. One of these tests is successfully creating a Delivery entity, and the second one simulates an error coming from the database.
To avoid relying on a physical instance of a persistence layer, we injected our DeliveryRepository instance using @MockBean, which creates and injects a mock of our component.
Documentation links:
Package the application
Spring boot also eases the application packaging either as a standalone jar or a docker image.
- To create a ready to run fat jar, execute
./gradlew bootJar. - To build a docker image, execute
./gradlew bootBuildImage.
Note that docker does not like uppercase characters in the image name, but we can easily customize the image name and version.
Documentation links:
Conclusion
Spring Boot can be used with a handful of annotations and will manage most of the configuration for you. However, most of the configuration can be overridden to provide your own behavior if necessary. This makes it a good framework to design proof of concepts while keeping room for optimization if the project grows specific needs.
If you want to know more about the framework, I can’t stress enough the quality of the Reference Documentation, which gives really good details.
If you want to play around with some code, you can find all those concepts on an example delivery API on GitHub.
