What is the role of the @QueryParam annotation?

Table of Contents

• Introduction
• Role of the @QueryParam Annotation
  • Mapping Query Parameters to Method Parameters
  • Flexibility in Data Binding
• How to Use @QueryParam
  • Example 1: Extracting Simple Query Parameters
  • Example Request
  • Example 2: Using Optional Parameters
  • Example Request with Optional Parameters
• Practical Use Cases of @QueryParam
  • Case 1: Filtering Data
  • Case 2: Sorting Data
  • Example Request for Sorting
  • Case 3: Paginating Data
  • Example Request for Pagination
• Conclusion

Introduction

In JAX-RS (Java API for RESTful Web Services), the @QueryParam annotation plays an essential role in extracting query parameters from the URL of an HTTP request. Query parameters are key-value pairs appended to the URL, and @QueryParam allows you to access these values in your resource methods. This is particularly useful for tasks like filtering, sorting, and passing additional information to the server via the URL. In this guide, we will explore the role of the @QueryParam annotation, how it works, and provide examples of its use.

Role of the @QueryParam Annotation

Mapping Query Parameters to Method Parameters

The primary function of the @QueryParam annotation is to bind query parameters from the HTTP request to method parameters in a JAX-RS resource. This enables you to handle dynamic input passed by the client through the URL, such as search filters or sorting criteria.

For example, a URL like:

contains two query parameters: age and status. Using @QueryParam, you can extract these values and use them in your resource method.

Flexibility in Data Binding

@QueryParam works with various data types, such as String, int, double, and even custom objects, as long as the types are compatible with the input format. It also allows for optional query parameters — if a parameter is not provided in the request, the method parameter can either have a default value or be null.

How to Use @QueryParam

The @QueryParam annotation is applied to method parameters, and it takes the name of the query parameter as its value. When the HTTP request is made, the value of the query parameter is automatically injected into the corresponding method parameter.

Example 1: Extracting Simple Query Parameters

In this example:

• The getUserInfo method extracts the age and status query parameters using the @QueryParam annotation.
• The URL GET http://localhost:8080/api/users?age=25&status=active will pass the values 25 for age and active for status to the method.

Example Request

A request like:

Will return:

Example 2: Using Optional Parameters

Query parameters are not always required. If a parameter is not included in the request, it can default to null or a specified default value in your method.

In this example:

• The query parameters minAge and maxAge are optional.
• If neither is provided, the method will return "No filtering applied", but if they are included, the method will return a filtered message.

Example Request with Optional Parameters

Will return:

Alternatively, if no parameters are provided:

Will return:

Practical Use Cases of @QueryParam

Case 1: Filtering Data

@QueryParam is commonly used to filter data in a RESTful API. For example, filtering a list of products by category, price, or availability status:

Case 2: Sorting Data

Another common use case is to sort data based on query parameters. For instance, you might sort users by their registration date or name:

Example Request for Sorting

Will return:

Case 3: Paginating Data

You can also use @QueryParam to implement pagination in your API. This is particularly useful for large datasets where you want to retrieve data in smaller chunks (pages).

Example Request for Pagination

Will return:

Conclusion

The @QueryParam annotation in JAX-RS is a powerful tool for extracting query parameters from HTTP requests in a RESTful API. It enables flexible handling of dynamic input, such as filtering, sorting, and pagination. By binding query parameters to method parameters, you can customize the behavior of your resource methods based on client input, improving the functionality and usability of your API. Whether you're working with simple or complex query parameters, understanding how to use @QueryParam is essential for building robust, dynamic RESTful services in Java.