Spring REST API custom query param
In the REST APIs, query parameters are used to control what data is returned to the client. Usually, the query parameter is a simple string or an array. There are cases when receiving a query as a string is not enough. This tutorial is about how to create a custom query param.
The use case:
Let's say we have the Java Spring Boot application with a REST GET API used to obtain information about customers from a relational database. For simplicity, I'm using here H2 in-memory database, each time the app is run the fake data is loaded into the database for testing and demonstration purposes. The data returned from this API contains id, full name, phone number, address line, city and state, and creation data. The application is very simple and has 3 layers: controller, service, and repository.
We have a new requirement. The API client has to be able to query customers residing in specified cities. For example, the client of an API wants to fetch the customers living in Sioux Falls South Dakota, and Chicago Illinois.
The solution:
Using a string as a request parameter won't do the trick. First, we have to define the way the combination of city and state will be passed and the separation between them.
The separaitor choice is easy because we will receive an array we will use the coma as a separator. The combination of city and state will be combined with the hyphen. So the request parameters will look like this:
/v1/customers?cities=Sioux Falls-SD,Chicago-ILTo be able to receive this query param we will have to perform a couple of steps. First, we have to create the DTO class which will hold separately as variables the city and state:
By default, the Spring binds the request parameter to a string. It is possible to bind the request param to a class. And this class has to have a public constructor which accepts a string as an argument.
Inside this constructor, we can perform the steps needed to parse the request parameter string and transform it into a list of objects from the above class.
The class is below:
This class has a constructor which accepts a string, and splits the string by a separator in this case it is a coma. Then create a substring before a hyphen for the city and after a hyphen for the state. Then with those two values, we create the object of the DTO class and add it to the collection.
To avoid any errors down the road and we will create the object if and only if both substrings will be not blank otherwise we will add the null to a collection. And if the collection has a null value the validation exception is thrown with the message informing the client about invalid input.
Here in the constructor, any flow can be added, you can, for example, create an enum for the states and throw an exception if a customer passes the value that doesn’t match any of the defined enum values. I think you got the idea.
After we assign this class to the request parameter in the controller. The Validated and Valid annotation has to be added to make request parameter validation work.
Then in the service layer, we have to create a dynamic query and pass it to the entity manager.
The complete code of the project you can find here:
The resource folder of a project has a postman collection. You can import it to a Postman and test the app on your own.
Conclusion
In this tutorial, I’ve explained how we can bind the custom class to a request parameter of a REST API. Thank you for reading! Please like and follow. If you have any questions or suggestions, please feel free to write me on my LinkedIn account.
