El aspecto de sus URL no tiene nada que ver con REST. Todo vale. En realidad es un "detalle de implementación". Entonces, al igual que cómo nombras tus variables. Todo lo que tienen que ser es único y duradero.
No pierdas demasiado tiempo en esto, solo haz una elección y cúmplelo / sé constante. Por ejemplo, si vas con jerarquías, entonces lo haces para todos tus recursos. Si va con parámetros de consulta ... etc. al igual que las convenciones de nomenclatura en su código.
Porque ? Hasta donde yo sé, una API "RESTful" debe ser navegable (ya sabes ... "Hypermedia como el motor del estado de la aplicación"), por lo tanto, a un cliente API no le importa cómo son tus URL siempre que sean válido (no hay SEO, ningún humano que necesite leer esas "URL amigables", excepto que puede ser para depurar ...)
Lo bueno / comprensible que es una URL en una API REST solo es interesante para usted como desarrollador de API, no como cliente de API, como lo sería el nombre de una variable en su código.
Lo más importante es que su cliente API sepa cómo interpretar su tipo de medio. Por ejemplo, sabe que:
- su tipo de medio tiene una propiedad de enlaces que enumera los enlaces disponibles / relacionados.
- Cada enlace se identifica por una relación (al igual que los navegadores saben que el enlace [rel = "stylesheet"] significa que es una hoja de estilo o rel = favico es un enlace a un favicon ...)
- y sabe lo que significan esas relaciones ("compañías" significa una lista de compañías, "buscar" significa una url con plantilla para hacer una búsqueda en una lista de recursos, "departamentos" significa departamentos del recurso actual)
A continuación se muestra un ejemplo de intercambio HTTP (los cuerpos están en yaml ya que es más fácil de escribir):
Solicitud
GET / HTTP/1.1
Host: api.acme.io
Accept: text/yaml, text/acme-mediatype+yaml
Respuesta: una lista de enlaces al recurso principal (empresas, personas, lo que sea ...)
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
Solicitud: enlace a empresas (usando el cuerpo de la respuesta anterior. Links.companies)
GET /companies HTTP/1.1
Host: api.acme.local
Accept: text/yaml, text/acme-mediatype+yaml
Respuesta: una lista parcial de compañías (debajo de los ítems), el recurso contiene enlaces relacionados, como un enlace para obtener las próximas dos compañías (body.links.next) y otro enlace (con plantilla) para buscar (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
Entonces, como ve si sigue los enlaces / relaciones, la forma en que estructura la parte de la ruta de sus URL no tiene ningún valor para su cliente API. Y si está comunicando la estructura de sus URL a su cliente como documentación, entonces no está haciendo REST (o al menos no Nivel 3 según el " modelo de madurez de Richardson ")