What are the path Parameters of a URI and its function?
It is first necessary to understand the concept of segments of path. Segments of path are parts that make up the value of path of a URI, separated by a bar (/
). For example, considering the following URI:
https://localhost/admin/users/edit/woss
The segments of path would be admin
, users
, edit
and woss
. The section defining the specifications of the path and segments of path is the Section 3.3 of RFC 3986. Quoting:
path = path-abempty ; begins with "/" or is empty
/ path-absolute ; begins with "/" but not "//"
/ path-noscheme ; begins with a non-colon segment
/ path-rootless ; begins with a segment
/ path-empty ; zero characters
path-abempty = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty = 0<pchar>
segment = *pchar
segment-nz = 1*pchar
segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" )
; non-zero-length segment without any colon ":"
pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
Analyzing the above definitions, it is possible to conclude that the specification itself does not consider the characters ;
, ,
and =
, defining the parameter as part of the segment.
That said, it is possible to define, then, the parameters of the path. The parameter of path is one way to provide more information on the path for the application, separating this from own path or other parameters by a semicolon (;
), may use the characters of equal (=
) and comma (,
) to construct the value of the parameter. For example, consider the following URI:
https://localhost/api;version=1.0,2.0
We should consider that version=1.0,2.0
is the parameter of path, separated from it by ;
, so-called version
, possessing two values: 1.0
and 2.0
. What this represents will depend solely on the resource requested by this URI, as well as the Leonan Carvalho commented in his reply, on the fact of path be a opaque value. By way of example, this URI could be requesting a public API that has different versions available and, with the parameter of path, the client is specifying which versions he accepts to handle his request.
A question that may arise at this time is about the difference between the parameters of path and the query URI, because it would be possible to do something equivalent by doing:
https://localhost/api?version=1.0,2.0
The two concepts are similar and have an almost identical proposal: provide a means for the client to pass more information of the requested resource to the server. The main difference is semantic: the information provided by query are associated with the URI as a whole, while the parameters of the path are associated with the segments to which they belong. In the URI https://localhost/api?version=1.0,2.0
we must understand that the value version=1.0,2.0
is associated with https://localhost/api
, that is, to the full URI, while at https://localhost/api;version=1.0,2.0
the same value will be associated only to api
, which is the segment of path to which the parameter is.
In this way, it is possible to indicate different parameter values to different segments in the URI without interference between them:
https://localhost/api;version=1.0/users/create;mode=strict
In the URI above, the parameter version=1.0
will be associated with the segment api
, while the parameter mode=strict
will be associated with the segment create
. Even, the names of the parameters could be the same without interfering with each other:
https://localhost/maps;version=0.1/api;version=1.2/location
The application would be (or should be) able to identify that version=0.1
refers to the resource represented in the segment maps
while varsion=1.2
refers to the resource represented by the segment api
. Something similar would not be possible to do only with query, except rename attribute names:
https://localhost/maps/api/location?version_maps=0.1&version_api=1.2
Another example that approaches everyday life to facilitate understanding would be the search for products in a virtual store through various filters. We imagine that the present user do the search for size M t-shirts and size 40 pants. A possible URI representing this resource could be:
https://localhost/products/search/camisetas;tamanho=M/calças;tamanho=40
A URI that defines the parameters represents a resource other than the URI that does not have the parameters? This is, /foo;v=1.0
is a different resource from /foo
?
The answer is: depends, but be very careful with that. Therefore, as already mentioned, the path of the URI is an opaque value and thus what exactly it represents is defined only in the implementation of the application. It can represent a different resource as well as represent the same resource, with a parameter that modifies its behavior. Care should be taken because, in particular, I have never seen an application that made use of the parameters of path and, considering the implementations of routers and dispatchers most common, especially under the MVC architecture, no (or almost no) application does the processing of parameters in the segments of the path, thus considering different resources. The format of the URI commonly considered is /controller/action/(parameters)?
, then informing a URI as /users/create;mode=strict
, the application would possibly consider create;mode=sctrict
as being the action to be executed, generating error.
To quote, in PHP:
<?php
$url = "https://localhost/products/search/camisetas;tamanho=M/calças;tamanho=40";
print_r(parse_url($url));
Results in:
Array
(
[scheme] => https
[host] => localhost
[path] => /products/search/camisetas;tamanho=M/calças;tamanho=40
)
See working on Ideone.
And in Python:
from urllib.parse import urlparse
url = "https://localhost/products/search/camisetas;tamanho=M/calças;tamanho=40"
print(urlparse(url))
Results in:
ParseResult(scheme='https', netloc='localhost', path='/products/search/camisetas;tamanho=M/calças', params='tamanho=40', query='', fragment='')
Note: the function urlparse
Python is able to correctly identify the parameter of the last segment of path.
See working on Ideone.
I saw some mention of that
path
andparameters
in the last paragraph of the section you linked (3.3 Path). He claims that with the exception of dot-Segments, thepath
URI is opaque. And use;
and=
would be a common practice, not necessarily recommended; it also says that,
may have the same semantics as;
, depending on the use only of who is implementing– Jefferson Quesado
@Jeffersonquesado Yes, but what does it really mean? What would be opaque in this context? That the user defines the
path
without knowing exactly how it will be handled by the application? And in the case of the parameters, what would be their real function? I’ve never seen this in practice and it’s hard to find any quote beyond the specification itself about it.– Woss
Opaque:
path
is opaque for URI recognition, so the URI does not see its inner parts. What does theparams
, I’m still researching here not to give an unfounded answer, but it seems that is vendor specific. I’m also after the information, but it’s a pretty big deal. I don’t think any library that reads URI cares too much about this explicitly, just the application that’s going to try to make sense of it– Jefferson Quesado
Exactly. From what I understood it could be used, for example, to specify the version of an API through the URI itself:
GET /api/users;v=1.0 HTTP/1.1
, or something like that. It seems that it is something that has been specified without a very clear purpose and each one uses as it wishes - which is kind of strange, because the URL could become inconsistent between different applications.– Woss
I’ll answer your question, I think if you’re going to approach everything would be too big, I’ll try to summarize, if you find that more details are still missing, add a comment that I add.
– Dorathoto