29

What's the difference between the JAX-RS @QueryParam and @MatrixParam? From the documents.The queryparam and matrixparam both can location one resource in special condition. So what's the use case difference?

ps:

Queryparam:

url ? key=value;

Matrixparam

url; key=value;

andih
  • 5,570
  • 3
  • 26
  • 36
jiafu
  • 6,338
  • 12
  • 49
  • 73
  • Does this answer your question? [URL matrix parameters vs. query parameters](https://stackoverflow.com/questions/2048121/url-matrix-parameters-vs-query-parameters) – Paco Abato Apr 26 '20 at 08:29
  • 1
    @PacoAbato This questions asks specifically in the context of JAX-RS. I'm not sure if the generic question asking is a suitable duplicate. – Mark Rotteveel Apr 26 '20 at 14:19

2 Answers2

22

The @MatrixParam annotation will apply to particular Resource present in URL and @QueryParam will apply to whole Request URL.

Take a example of any Supermarket, If you want all fruits which will be satisfied multiple conditions like type=fruits and price range starts from 300 and list out matching 10 fruits, you can go for below API Design,

http://dev.brandstore.com/inventory/grocery;type=fruits/price;range=300/?limit=10

In above example, first Matrix Param type=fruits is applying to only grocery resource same range=300 is applying to only price resource but Query Param for pagination limit=10 is applying to whole Request URL. And yes, If only query parameters were used, you would end up with parameters like "grocery_type" and "grocery_price" and you would lose the clarity added by the locality of the parameters within the request.

Hardik Patel
  • 1,033
  • 1
  • 12
  • 16
  • 1
    Good explanation, its actually makes sense. – Vicky Mar 24 '18 at 17:32
  • @Hardik Patel could you tell me how the link will be if we use queryParam instead of @MatrixParam? i Just want to see the clarity point you mentioned.Please answer – JAVA Sep 20 '18 at 22:53
  • what is the spring REST equivalent annotation to @MatrixParam. – rakeeee Jan 31 '19 at 15:11
  • 1
    @JAVA If you use query params instead of matrix params, then the link would become: `http://dev.brandstore.com/inventory/grocery/price/?grocery_type=type=fruits&price_range=300&limit=10` I have used query param values as `grocery_type` and `price_range`. You are free to use any param name you want. Point is if you put these in query params, then you will have to add context to the param name like grocery_type signifies that it is the type of grocery. You just can't use `type` like you did in matrix param since it becomes confusing in query param. – Udit Agarwal Feb 28 '19 at 10:38
17

As stated in this Oracle documentation:

The @PathParam and the other parameter-based annotations, @MatrixParam, @HeaderParam, @CookieParam, @FormParam obey the same rules as @QueryParam. @MatrixParam extracts information from URL path segments. @HeaderParam extracts information from the HTTP headers. @CookieParam extracts information from the cookies declared in cookie related HTTP headers.

Example (drawn from here):

@Path("/books")
public class BookService {

    @GET
    @Path("{year}")
    public Response getBooks(@PathParam("year") String year,
            @MatrixParam("author") String author,
            @MatrixParam("country") String country) {

        return Response
            .status(200)
            .entity("getBooks is called, year : " + year
                + ", author : " + author + ", country : " + country)
            .build();

    }

}

See following URI patterns and result:

  1. URI Pattern : “/books/2012/”

    getBooks is called, year : 2012, author : null, country : null

  2. URI Pattern : “/books/2012;author=andih”

    getBooks is called, year : 2012, author : andih, country : null

  3. URI Pattern : “/books/2012;author=andih;country=germany”

    getBooks is called, year : 2012, author : andih, country : germany

  4. URI Pattern : “/books/2012;country=germany;author=andih”

    getBooks is called, year : 2012, author : andih, country : germany

For an explanation of the difference you may have a look at URL matrix parameters vs. request parameters

Community
  • 1
  • 1
andih
  • 5,570
  • 3
  • 26
  • 36
  • You can find a very good explanation of a matrix paramater in Tim Sylvester's answer in [URL matrix parameters vs. request parameters](http://stackoverflow.com/questions/2048121/url-matrix-parameters-vs-request-parameters). The link was already provided as part of my answer. – andih Oct 08 '12 at 12:42
  • 5
    Your example looks very similar to the code at this website. If you copied it from there, you should give proper attribution. http://www.mkyong.com/webservices/jax-rs/jax-rs-matrixparam-example/ – EdgeCase Nov 14 '14 at 14:19
  • 7
    @OhadR The key here is: `@MatrixParam` extracts information from URL path *segments*. So you can have `@MatrixParam` in every path segment, even with the same name, but their scope is a path segment. `@QueryParam` is, well, query parameters scoped. In other word you can have for example: `/books;country=germany/2012;country=france;author=Vian` and it's legal, and first country (sticked to books) is about where the books were issued and the second country param (sticked to year) is about from what country they came from. – Cromax Jan 14 '15 at 21:38
  • @EdgeCase The introductory prose also appears to have been lifted from the Oracle docs at http://docs.oracle.com/javaee/6/tutorial/doc/gilik.html#gipze (search for "and the other"). – Joshua Taylor Apr 17 '15 at 22:37
  • @JoshuaTaylor - The author does mention 'As stated in this Oracle documentation:'. Looks like you missed that. – user1860447 May 11 '15 at 22:10
  • @user1860447 If you look at the edit history, that acknowledgment was [added by a moderator on May 6, 2015](http://stackoverflow.com/revisions/10184695/3) (probably in response to a flag). It was **not** present when I posted my comment. – Joshua Taylor May 11 '15 at 22:11