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:
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:
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¶mA=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:
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:
For instance, an API GET request for the latest revision-2 articles of author015 from the CS group could be something like this:
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.