A aparência dos seus URLs não tem nada a ver com o REST. Qualquer coisa serve. Na verdade, é um "detalhe de implementação". Assim como você nomeia suas variáveis. Tudo o que precisam ser únicos e duráveis.
Não perca muito tempo com isso, basta fazer uma escolha e cumpri-lo / ser consistente. Por exemplo, se você segue hierarquias, o faz para todos os seus recursos. Se você usar parâmetros de consulta ... etc, assim como as convenções de nomenclatura no seu código.
Por quê então ? Tanto quanto eu sei que uma API "RESTful" deve ser navegável (você sabe ... "Hipermídia como o mecanismo do estado do aplicativo"), portanto, um cliente de API não se importa com o que são seus URLs, desde que sejam válido (não há SEO, nenhum ser humano que precise ler esses "URLs amigáveis", exceto para depuração ...)
O quão agradável / compreensível é um URL em uma API REST é interessante apenas para você como desenvolvedor da API, não como cliente da API, como seria o nome de uma variável em seu código.
O mais importante é que seu cliente de API saiba como interpretar seu tipo de mídia. Por exemplo, ele sabe que:
- seu tipo de mídia possui uma propriedade de links que lista os links disponíveis / relacionados.
- Cada link é identificado por um relacionamento (assim como os navegadores sabem que link [rel = "stylesheet"] significa que é uma folha de estilos ou rel = favico é um link para um favicon ...)
- e sabe o que significam esses relacionamentos ("empresas" significa uma lista de empresas, "pesquisa" significa um URL modelo para fazer uma pesquisa em uma lista de recursos, "departamentos" significa departamentos do recurso atual)
Abaixo está um exemplo de troca HTTP (os corpos estão no yaml, pois é mais fácil escrever):
Solicitação
GET / HTTP/1.1
Host: api.acme.io
Accept: text/yaml, text/acme-mediatype+yaml
Resposta: uma lista de links para o recurso principal (empresas, pessoas, o que for ...)
HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:04:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml
# body: this is your API's entrypoint (like a homepage)
links:
# could be some random path https://api.acme.local/modskmklmkdsml
# the only thing the API client cares about is the key (or rel) "companies"
companies: https://api.acme.local/companies
people: https://api.acme.local/people
Pedido: link para empresas (usando body.links.companies da resposta anterior)
GET /companies HTTP/1.1
Host: api.acme.local
Accept: text/yaml, text/acme-mediatype+yaml
Resposta: uma lista parcial de empresas (nos itens), o recurso contém links relacionados, como o link para obter as próximas empresas (body.links.next) e outro (modelo) para a pesquisa (body.links.search)
HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:06:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml
# body: representation of a list of companies
links:
# link to the next page
next: https://api.acme.local/companies?page=2
# templated link for search
search: https://api.acme.local/companies?query={query}
# you could provide available actions related to this resource
actions:
add:
href: https://api.acme.local/companies
method: POST
items:
- name: company1
links:
self: https://api.acme.local/companies/8er13eo
# and here is the link to departments
# again the client only cares about the key department
department: https://api.acme.local/companies/8er13eo/departments
- name: company2
links:
self: https://api.acme.local/companies/9r13d4l
# or could be in some other location !
department: https://api2.acme.local/departments?company=8er13eo
Então, como você vê se segue o caminho dos links / relações, como você estrutura a parte do caminho dos seus URLs não tem valor para o seu cliente de API. E se você está comunicando a estrutura de seus URLs ao cliente como documentação, não está fazendo REST (ou pelo menos não está no nível 3, conforme " Modelo de maturidade de Richardson ")