1. Introduction

Changeable components of an URL are called API parameters. They determine the kind of action we wish to take on the URL’s resource. Each parameter has a name, type of value, and an optional description. Among others, m****atrix and query parameters are API parameters.

In this tutorial, we’ll discuss the advantages and disadvantages of using matrix and query parameters while submitting an HTTP request.

2. REST API Parameters

REST API uses URLs to specify the resource’s internet address. A URL includes the following components:

  • Scheme: Denotes the protocol such as HTTP or HTTPS
  • Authority: The registered name of the resource, such as www.baeldung.com
  • Path: The full path of the resource on the web server (like /res/findByAuthorType)
  • Query String: The ampersand-delimited name-value pairs (e.g., offset=0&page=1)
  • Fragment: It’s an optional component and directs users to a secondary resource.

The query parameters (parts of a query string) enable passing the desired information to the web server:

This shows the components of URI

For example, when designing a REST API, we must choose which query parameters to include in the API to modify the response from a server.

However, sometimes, we find an additional parameter separated by “;” before the query parameter:

shows Matrix parameter in a url

Why would we need  [;Param] when we can pass information using query parameters? The reason is that sometimes, we need to pass parameters to the resources identified by query parameters. That’s what matrix parameters are for.

3. Query Parameters

Query parameters are more common and follow the question mark. They come after the path component but before the fragment.

3.1. Advantages and Disadvantages

There are several advantages of query parameters. They need not be unique because a parameter can be repeated multiple times in a URL (e.g. ParamA=val1&paramA=val2). As long as the variables are correct, it doesn’t matter in what order they appear in the query string. We use the ampersand to delimit them.

By default, a browser provides query parameters and uses them when submitting a form using the GET method

It’s equally important to know that there are disadvantages. Query parameters are used for the whole request. Each resource handler gets all the query parameters when using a framework like JAX-RS, which could result in conflicts and confusion.

4. Matrix Parameters

Their purpose is to refine the search since they provide more flexibility. In contrast to query parameters, a URL can include matrix parameters anywhere within it.

Further, query parameters apply to the entire request, but matrix parameters apply to a particular path element.

4.1. Advantages

There is better readability, and the character “&”doesn’t need to be encoded or decoded in XML documents.

They are specific to target path elements and beneficial when sending a sophisticated REST-style query to numerous tiers of resources and sub-resources. We can use them anywhere within our URLs.

Also, matrix parameters can have multiple values (e.g., matrixParam=val1,val2).

4.2. Disadvantages

There are very few frameworks, e.g. JAX-RS, that support matrix parameters. The matrix parameters become query parameters when a browser submits a form using the GET method.

Sometimes, URLs beginning with “?” are not cached, resulting in the same task ending up with two different types of parameters. By default, a browser doesn’t create matrix parameters.

5. Example

Let’s take an example where we’re using all URL syntax components for identifying the latest articles at www.baeldung.com:

Full syntax in URL

With query parameters only, we can’t use an additional identifier such as a directory anywhere in the above URL. This is why an additional mechanism like a matrix parameter is required for passing new parameters.

So, the URL with a matrix parameter will specify not just that we want the latest articles but also which directory to search:

Full URL with Matrix parameter

For instance, an API GET request for the latest revision-2 articles of author015 from the CS group could be something like this:

API GET Request with Matrix Parameter

Since matrix parameters refine the search, both types of parameters are sometimes necessary.

6. Key Difference Between Query & Matrix Parameters

Here are the key differences between matrix and query parameters:

Context

Query Parameters

Matrix Parameters

Scope

Apply to the entire request

Apply to a specific path element

Separator

A question mark separates the query parameters from the path

A semicolon separates matrix parameters from the hierarchical path segments

Position

At the end of a URL

Can appear anywhere in a URL

Separator for multiple parameters

Separated by “;” or “&”

Separated by “;”

Structure

Made up of one or more pairs of names and values

Each parameter may also have more than one value separated by “,”

7. Conclusion

In this article, we talked about query and matrix parameters. The distinction is that while query parameters apply to the entire request, matrix parameters only apply to a path element. Also, the former are more common.