Matrix parameters are another way of defining parameters in the URI path template. The matrix parameters take the form of name-value pairs in the URI path, where each pair is preceded by a semicolon (;). For instance, the URI path that uses a matrix parameter to list all departments in Bangalore city looks like /departments;city=Bangalore.

The @javax.ws.rs.MatrixParam annotation injects the matrix parameter value into a class field, a resource class bean property (the getter method for accessing the attribute), or a method parameter.

The following code snippet demonstrates the use of the @MatrixParam annotation to extract the matrix parameters present in the request. The URI path used in this example looks like /departments/matrix;name=IT;city=Bangalore:

@GET @Produces(MediaType.APPLICATION_JSON) @Path("matrix") 
public List<Department> findAllDepartmentsByNameWithMatrix(
                                @MatrixParam("name") String deptName, 
                                @MatrixParam("city") String locationCode) {            
     List<Department> depts=findAllDepartmentsFromDB(deptName, city); 
     return depts; 
}
 

You can use PathParam, QueryParam, and MatrixParam to pass the desired search parameters to the REST APIs. Now, you may ask, "When to use what?"
Although there are no strict rules here, a very common practice followed by many is to use PathParam to drill down to the entity class hierarchy and locate the specific resource.  For example, you may use the URI of the following form to identify an employee working in a specific department: /departments/{dept}/employees/{id}.
QueryParam can be used for specifying attributes to locate the resources. For example, you may use URI with QueryParam to identify employees who joined on January 1, 2015, which may look like /employees?doj=2015-01-01.

The MatrixParam annotation is not used frequently. This is useful when you need to make a complex REST style query to multiple levels of resources and subresources. MatrixParam is applicable to a particular path element, while the query parameter is applicable to the entire request.