30
  • O que são os path parameters de uma URI e qual sua função?
  • 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?

Se possível, dê exemplos de sua aplicação/função.

Pois até então, o formato da URI que eu conhecia era:

  foo://example.com:8042/over/there?name=ferret#nose
  \_/   \______________/\_________/ \_________/ \__/
   |           |            |            |        |
scheme     authority       path        query   fragment

Mas hoje acabei percebendo a existência de mais um item:

  foo://example.com:8042/over/there;param=value;p2;p3?name=ferret#nose
  \_/   \______________/\_________/ \_______________/ \_________/ \__/
   |           |            |              |              |         |
scheme     authority       path          params         query   fragment

Onde a RFC3986 recomenda utilizar o caractere ; para separar os parâmetros, o caractere = para separar o nome do valor, e o caractere , para separar múltiplos valores de um mesmo parâmetro.

5
  • Eu vi alguma menção a esse path e parameters no último parágrafo da seção que você linkou (3.3 Path). Ele afirma que, com exceção dos dot-segments, o path 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á implementando Commented 25/08/2017 às 12:56
  • @JeffersonQuesado Sim, mas o que isso realmente significa? O que seria opaco neste contexto? Que o usuário define o path 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.
    – Woss
    Commented 25/08/2017 às 13:02
  • Opaco: path é opaco para o reconhecimento da URI, portanto a URI não enxerga suas partes interiores. Sobre o que significa os params, 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 isso Commented 25/08/2017 às 13:07
  • 1
    Exatamente. Pelo o que entendi poderia ser utilizado, por exemplo, para especificar a versão de uma API através da própria URI: GET /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.
    – Woss
    Commented 25/08/2017 às 13:12
  • vou responder sua pergunta, acho que se for abordar tudo ficaria muito grande, vou tentar resumir, se achar que ainda falta mais detalhes, adicione um comentário que eu complemento.
    – Dorath
    Commented 25/08/2017 às 17:06

3 Respostas 3

14

Existe uma diferença sutil entre Path params e params Query que eu tomo a liberdade de traduzir para Parâmetros do caminho da Url e Parâmetros de Consulta

Ambas fazem a mesma coisa porém de formas diferentes.

Parâmetros da URL

  • Deixa a url amigável (SEO, usuário, etc)

  • Em teoria, é algo importante na url, algo de valor

  • Caso o parâmetro passado seja invalido pode ocorrer 404

    ex: GET parentes/avo/detalhes

Parâmetros de Query (Ou Querystring)

  • Urls menos amigáveis para SEO (difícil entendimento do usuário)

  • Em teoria é algo supérfluo para execução da url, como filtros, ordenações, etc.

  • Não causa 404, caso o parametro seja inválido

  • ex: GET parentes/detalhes?tipo=avo

O padrão para parâmetros para querystring é:

| Tipo    | Descrição                                         |
|---------|---------------------------------------------------|
| ?       | antes do primeiro valor                           |
| {param} | Nome do parâmetro                                 |
| =       | separação do parâmetro e valor com sinal de igual |
| {value} | valor do parâmetro                                |
| &       | para separar demais parâmetros                    |

ex: url/pagina?parametro1=valor&parametro2=valor


Pra SEO a primeira forma é a recomandada, desde que o parâmetro seja algo útil na página, se for apenas um filtro, pode se utilizar a 2ª forma.

Quem vai diferenciar o que é um caminho da url ou o que é um simples parâmetro é você no desenvolvido, com base no bom senso.

O próprio artigo indicado diz:

3.4 . Query

O componente de consulta contém dados não-hierárquicos que, juntamente com dados do caminho ( Seção 3.3 ), serve para identificar um recurso dentro do escopo do esquema do URI e autoridade (caso existam). O componente de consulta é indicado pelo primeiro caractere ("?") E terminado por um sinal ("#") ou até o final do URI.

3.3 . Path

O componente path contém dados, geralmente organizados de forma hierarquica, que, juntamente com dados no componente de consulta não hierárquica ( Seção 3.4 ), serve para identificar um recurso dentro do escopo do esquema de URI e autoridade de nomeação (se houver). O caminho é encerrado pelo primeiro ponto de interrogação ("?") ...

Com base nesse entendimento, podemos responder as perguntas:

path parameters de uma URI e qual sua função?

A função é passar parâmetros de forma hierárquica para uma pagina, esses parâmetros são impreencindíveis para o funcionamento desta página, diferente das query que não são obrigatórias.

UPDATE: Após analise sobre a função do ponto-virgula e principalmente da resposta do @LeonanCarvalho;

Por exemplo, o ponto-e-vírgula (";") e os caracteres reservados iguais ("=") são freqüentemente usados para delimitar parâmetros e valores de parâmetros aplicáveis a esse seguimento. O caracter reservado da vírgula (",") é freqüentemente usado para fins semelhantes. Por exemplo, um URI producer pode usar um segmento como "nome; v = 1.1" para indicar uma referência à versão 1.1 do "nome", enquanto outro pode usar um segmento como "nome, 1.1" para indicar o mesmo.

Vejo que o ponto-vírgula tem o mesmo efeito do sinal de igual, servem para separar valores. Lembrando que alguns sistemas podem interpretar o ; como código de SQL Injection, causando problemas ou erros 500.1 no site.


Mais informações em:

https://softwareengineering.stackexchange.com/questions/270898/designing-a-rest-api-by-uri-vs-query-string

https://stackoverflow.com/questions/30967822/when-do-i-use-path-params-vs-query-params-in-a-restful-api

https://www.rfc-editor.org/rfc/rfc3986#section-3.4

11
  • 1
    "Sinal de número # personagem"? Acho que o tradutor pregou uma peça Commented 25/08/2017 às 17:27
  • Muito bom o link do softwareengineering Commented 25/08/2017 às 17:56
  • Não ficou claro a parte dos parâmetros do path, pois parece que você considerou apenas o path em sim. Se eu especificar uma URL como /foo/baz;version=1.0, o path será o /foo/baz e os parâmetros do path será version=1.0 (perceba que não é a query). Não vi na sua resposta nenhuma referência a este segundo.
    – Woss
    Commented 25/08/2017 às 19:25
  • a query só é adicionada após o ? tudo antes é parametro de url
    – Dorath
    Commented 28/08/2017 às 14:17
  • 2
    Esta pergunta/resposta está a ser debatida no Meta.
    – Sergio
    Commented 30/08/2017 às 14:06
9

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.

3
  • 1
    Esta pergunta e respostas estão a ser debatidas no Meta. Comentários ao conteúdo da resposta e possíveis razões de -1 são certamente bem-vindas aqui.
    – Sergio
    Commented 30/08/2017 às 14:25
  • Downvote gratuito é simplesmente irritante, mostra como as pessoas não entendem que suas respostas estão erradas e começam a atacar outras respostas porque simplesmente se sentem vitimadas sem serem.
    – Syzoth
    Commented 30/08/2017 às 15:24
  • Só pra constar eu dei +1 nessa resposta, ela não invalida a minha e trás uma abordagem diferente, mais " dentro do código." Commented 30/08/2017 às 18:58
5
+50

A única forma de interpretar o que está numa RFC é voltando à ela e buscar pela definição específica buscando dentro da sua tipologia os significados para cada um dos elementos.

Observe a seção 3.3, que define Path :

Além de segmentos de pontos em Path hierárquicos, um segmento de Pathé considerado opaco pela sintaxe genérica. As aplicações de produção de URI geralmente usam os caracteres reservados permitidos em um segmento para delimitar subcomponentes [metadados] específicas do esquema ou de desresferência específicos. Por exemplo, o ponto-e-vírgula (";") e os caracteres reservados iguais ("=") são freqüentemente usados para delimitar parâmetros e valores de parâmetros aplicáveis a esse seguimento. O caracter reservado da vírgula (",") é freqüentemente usado para fins semelhantes. Por exemplo, um URI producer pode usar um segmento como "nome; v = 1.1" para indicar uma referência à versão 1.1 do "nome", enquanto outro pode usar um segmento como "nome, 1.1" para indicar o mesmo. Os tipos de parâmetros podem ser definidos por semântica específica do esquema, mas na maioria dos casos a sintaxe de um parâmetro é específica para a implementação do algoritmo de desreferência do URI. (traduçao literal)

Podemos dizer então que path parameters são elementos do Path URI para implementação específica do algoritimo de desreferência, ou seja, interpretar o valor contido.

Na programação, desreferênciar é acessar informações no endereço contido por um ponteiro. A sintaxe do desreferenciamento varia entre as linguagens de computador.

Respondendo a pergunta,

path parameters de uma URI e qual sua função?

No caso da URI, o path parameters tem a função de extender informações de um seguimento do Path afim de adicionar informações extras (metadados ou subcomponentes) à um recurso. Como a implementação do Path é opaca, a maneira em que ele será usado e interpretado depende exclusivamente do programa que faz a desreferência do schema.

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?[v=1.0]

Sim, são difernetes, no primeiro caso "foo" tem o metadado v com valor 1.0, e na segunda toda a URI tem um parâmetro quetry string v com valor 1.0.

Convertendo para um JSON por exemplo teríamos:

  • /foo;v=1.0

    { "foo": { v: 1.0 } }

e

  • /foo?v=1.0

    { "foo":null, "v": 1.0 }

Porém essa interpretação para JSON é relativa, já que " na maioria dos casos a sintaxe de um parâmetro é específica para a implementação do algoritmo de desreferência do URI. " Ou seja, a forma como a síntax da URI é interpretada depende exclusivamente do software que faz a desreferênciação.

À carater de exemplificação, observe a API do Generic Enabler do Fiware chamado "Orion Context Broker", em Specifications>Geographical Queries

Geographical queries are specified using the following parameters: georel is intended to specify a spatial relationship (a predicate) between matching entities and a reference shape (geometry). It is composed of a token list separated by ';'. Example:

georel=near;maxDistance:1000

Embora a síntaxe do modelo de desreferência do schema da API foi impregrado na Query ao invés do Path o schema poderia ter sido impregado como um Path parâmetro geo recebeu algums subcomponentes (maxDistance 1000 ) que permitiram o uso mais agregado da api já que é possível formar um shema mais complexo como por exemplo:

georel=coveredBy&geometry=polygon&coords=25.774,-80.190;18.466,-66.118;32.321,-64.757;25.774,-80.190

Trazendo essa lógica para um modelo que se use exclusivamente Path, poderiamos modelar o schema da seguinte forma:

/api/geoquery/(geoparams+)

Que permitiria chamadas como esta:

/api/geoquery/georel;type=near;maxDistance:1000

ou

/api/geoquery/georel;type=coveredBy;geometry=polygon;coords=25.774,-80.190;18.466,-66.118;32.321,-64.757;25.774,-80.190

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .