O que são os path parameters de uma URI e qual sua função?
É necessário primeiramente entender o conceito de segmentos de path. Segmentos de path são partes que compõem o valor do path de uma URI, separados por uma barra (/
). Por exemplo, considerando a seguinte URI:
https://localhost/admin/users/edit/woss
Os segmentos de path seriam admin
, users
, edit
e woss
. A seção que define as especificações do path e segmentos do path é a seção 3.3 da RFC 3986. A citar:
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 / ":" / "@"
Analisando as definições acima, é possível concluir que a própria especificação não considera os caracteres ;
, ,
e =
, que definem o parâmetro, como parte do segmento.
Dito isso, é possível definir, então, os parâmetros do path. O parâmetro do path é uma forma de fornecer mais informações sobre o path para a aplicação, separando esta do próprio path ou de outros parâmetros por um ponto e vírgula (;
), podendo utilizar os caracteres de igual (=
) e vírgula (,
) para construir o valor do parâmetro. Por exemplo, considerando a seguinte URI:
https://localhost/api;version=1.0,2.0
Devemos considerar que version=1.0,2.0
é o parâmetro do path, separado do mesmo pelo ;
, denominado version
, possuindo dois valores: 1.0
e 2.0
. O que isso representa dependerá exclusivamente do recurso solicitado por esta URI, assim como o Leonan Carvalho comentou em sua resposta, sobre o fato do path ser um valor opaco. A título de exemplo, esta URI poderia estar solicitando uma API pública que possui diferentes versões disponíveis e, com o parâmetro do path, o cliente está especificando quais as versões que ele aceita para tratar sua requisição.
Um questionamento que pode surgir neste momento é sobre a diferença entre os parâmetros do path e a query da URI, pois seria possível fazer algo equivalente fazendo:
https://localhost/api?version=1.0,2.0
Os dois conceitos são semelhantes e possuem uma proposta quase idêntica: fornecer um meio de o cliente passar mais informações do recurso solicitado ao servidor. A principal diferença é semântica: as informações passadas pela query são associadas a URI como um todo, enquanto os parâmetros do path são associados aos segmentos ao qual pertencem. Na URI https://localhost/api?version=1.0,2.0
devemos entender que o valor version=1.0,2.0
está associado à https://localhost/api
, isto é, à URI completa, enquanto em https://localhost/api;version=1.0,2.0
o mesmo valor estará associado apenas à api
, que é o segmento do path ao qual o parâmetro se encontra.
Desta forma, é possível indicar diferentes valores de parâmetros a diferentes segmentos na URI sem que haja interferência entre eles:
https://localhost/api;version=1.0/users/create;mode=strict
Na URI acima, o parâmetro version=1.0
estará associado ao segmento api
, enquanto o parâmetro mode=strict
estará associado ao segmento create
. Inclusive, os nomes dos parâmetros poderiam ser os mesmos sem interferirem entre si:
https://localhost/maps;version=0.1/api;version=1.2/location
A aplicação seria (ou deveria ser) capaz de identificar que version=0.1
refere-se ao recurso representado no segmento maps
enquanto varsion=1.2
refere-se ao recurso representado pelo segmento api
. Algo semelhante não seria possível fazer apenas com query, exceto renomear os nomes dos atributos:
https://localhost/maps/api/location?version_maps=0.1&version_api=1.2
Outro exemplo que se aproxima do cotidiano para facilitar o entendimento seria a busca de produtos em uma loja virtual através de vários filtros. Imaginamos que o usuário presente fazer a busca por camisetas de tamanho M e calças tamanho 40. Uma possível URI que representa este recurso poderia ser:
https://localhost/products/search/camisetas;tamanho=M/calças;tamanho=40
Uma URI que define os parâmetros representa um recurso diferente da URI que não possui os parâmetros? Isto é, /foo;v=1.0
é um recurso diferente de /foo
?
A resposta é: depende, mas tome muito cuidado com isso. Depende, pois, como já citado, o path da URI é um valor opaco e, assim, o que exatamente ela representa é definido apenas na implementação da aplicação. Pode representar um recurso diferente como também pode representar um mesmo recurso, com um parâmetro que modifica seu comportamento. O cuidado deve ser tomado pois, particularmente, nunca vi uma aplicação que fizesse o uso dos parâmetros de path e, considerando as implementações de routers e dispatchers mais comuns, principalmente sob a arquitetura MVC, nenhuma (ou quase nenhuma) aplicação faz o processamento dos parâmetros nos segmentos do path, considerando assim, recursos diferentes. O formato da URI comumente considerado é /controller/action/(parameters)?
, então informando uma URI como /users/create;mode=strict
, a aplicação possivelmente consideraria create;mode=sctrict
como sendo a ação a ser executada, gerando erro.
A citar, em PHP:
<?php
$url = "https://localhost/products/search/camisetas;tamanho=M/calças;tamanho=40";
print_r(parse_url($url));
Resulta em:
Array
(
[scheme] => https
[host] => localhost
[path] => /products/search/camisetas;tamanho=M/calças;tamanho=40
)
Veja funcionando no Ideone.
E em Python:
from urllib.parse import urlparse
url = "https://localhost/products/search/camisetas;tamanho=M/calças;tamanho=40"
print(urlparse(url))
Resulta em:
ParseResult(scheme='https', netloc='localhost', path='/products/search/camisetas;tamanho=M/calças', params='tamanho=40', query='', fragment='')
Nota: a função urlparse
do Python é capaz de identificar corretamente o parâmetro do último segmento do path.
Veja funcionando no Ideone.
path
eparameters
no último parágrafo da seção que você linkou (3.3 Path). Ele afirma que, com exceção dos dot-segments, opath
da URI é opaco. E usar o;
e=
seria uma prática comum, não necessariamente recomendada; ele também fala que,
pode ter a mesma semântica do;
, dependendo o uso só de quem está implementandopath
sem saber exatamente como ele será tratado pela aplicação? E no caso dos parâmetros, qual seria a real função deles? Nunca vi isso na prática e é difícil achar qualquer citação além da própria especificação sobre isso.path
é opaco para o reconhecimento da URI, portanto a URI não enxerga suas partes interiores. Sobre o que significa osparams
, eu ainda estou pesquisando aqui para não dar uma resposta não embasada, mas parece que é vendor specific. Também estou atrás da informação, mas é uma coisa bem arcana isso. Acho que nenhuma biblioteca que lê URI se preocupa muito com isso explicitamente, só a aplicação que vai tentar dar algum sentido pra issoGET /api/users;v=1.0 HTTP/1.1
, ou algo do gênero. Parece que é algo que foi especificado sem um propósito muito claro e cada um usa como deseja - o que é meio estranho, pois a URL poderia se tornar inconsistente entre diferentes aplicações.