URL matrix parameters vs. query parameters

Solution 1:

The important difference is that matrix parameters apply to a particular path element while query parameters apply to the request as a whole. This comes into play when making a complex REST-style query to multiple levels of resources and sub-resources:

http://example.com/res/categories;name=foo/objects;name=green/?page=1

It really comes down to namespacing.

Note: The 'levels' of resources here are categories and objects.

If only query parameters were used for a multi-level URL, you would end up with

http://example.com/res?categories_name=foo&objects_name=green&page=1

This way you would also lose the clarity added by the locality of the parameters within the request. In addition, when using a framework like JAX-RS, all the query parameters would show up within each resource handler, leading to potential conflicts and confusion.

If your query has only one "level", then the difference is not really important and the two types of parameters are effectively interchangeable, however, query parameters are generally better supported and more widely recognized. In general, I would recommend that you stick with query parameters for things like HTML forms and simple, single-level HTTP APIs.

Solution 2:

In addition to Tim Sylvester's answer I would like to provide an example of how matrix parameters can be handled with JAX-RS .

1. Matrix parameters at the last resource element

   http://localhost:8080/res/categories/objects;name=green
   

   You can access them using the @MatrixParam annotation

   @GET
   @Path("categories/objects")
   public String objects(@MatrixParam("name") String objectName) {
     return objectName;
   }
   

   Response

   green
   

   But like the Javadoc states

   Note that the @MatrixParam annotation value refers to a name of a matrix parameter that resides in the last matched path segment of the Path-annotated Java structure that injects the value of the matrix parameter.

   ... what brings us to point 2

2. Matrix parameters in the middle of an URL

   http://localhost:8080/res/categories;name=foo/objects;name=green
   

   You can access matrix parameters anywhere using path variables and @PathParam PathSegment.

   @GET
   @Path("{categoryVar:categories}/objects")
   public String objectsByCategory(@PathParam("categoryVar") PathSegment categorySegment, 
                                   @MatrixParam("name") String objectName) {
     MultivaluedMap<String, String> matrixParameters = categorySegment.getMatrixParameters();
     String categorySegmentPath = categorySegment.getPath();
     String string = String.format("object %s, path:%s, matrixParams:%s%n", objectName,
             categorySegmentPath, matrixParameters);
     return string;
   }
   

   Response

   object green, path:categories, matrixParams:[name=foo]
   

   Since the matrix parameters are provided as a MultivaluedMap you can access each by

   List<String> names = matrixParameters.get("name");
   

   or if you only need the first one

   String name = matrixParameters.getFirst("name");
   

3. Get all matrix parameters as one method parameter

   http://localhost:8080/res/categories;name=foo/objects;name=green//attributes;name=size
   

   Use a List<PathSegment> to get them all

   @GET
   @Path("all/{var:.+}")
   public String allSegments(@PathParam("var") List<PathSegment> pathSegments) {
     StringBuilder sb =  new StringBuilder();
   
     for (PathSegment pathSegment : pathSegments) {
       sb.append("path: ");
       sb.append(pathSegment.getPath());
       sb.append(", matrix parameters ");
       sb.append(pathSegment.getMatrixParameters());
       sb.append("<br/>");
     }
   
     return sb.toString();
   }
   

   Response

   path: categories, matrix parameters [name=foo]
   path: objects, matrix parameters [name=green]
   path: attributes, matrix parameters [name=size]
   

Solution 3:

--Too important to be relegated to comment section.--

I'm not sure what the big deal is with matrix URLs. According to the w3c design article that TBL wrote, it was just a design idea and explicitly states that it's not a feature of the web. Things like relative URLs aren't implemented when using it. If you want to use it, that's fine; there's just no standard way to use it because it's not a standard.

— Steve Pomeroy.

So short answer is, if you need RS for business purpose, you are better off using request parameter.