¿Cuáles son las mejores prácticas para los recursos anidados REST?

Por lo que puedo decir, cada recurso individual debe tener solo una ruta canónica . Entonces, en el siguiente ejemplo, ¿cuáles serían los buenos patrones de URL?

Tomemos como ejemplo un resto de representación de empresas. En este ejemplo hipotético, cada compañía posee 0 o más departamentos y cada departamento posee 0 o más empleados.

Un departamento no puede existir sin una empresa asociada.

Un empleado no puede existir sin un departamento asociado.

Ahora me parece que la representación natural de los patrones de recursos es.

• /companies Una colección de compañías - Acepta poner para una nueva compañía. Obtenga para toda la colección.
• /companies/{companyId}Una empresa individual. Acepta GET, PUT y DELETE
• /companies/{companyId}/departmentsAcepta POST para un nuevo artículo. (Crea un departamento dentro de la empresa).
• /companies/{companyId}/departments/{departmentId}/
• /companies/{companyId}/departments/{departmentId}/employees
• /companies/{companyId}/departments/{departmentId}/employees/{empId}

Dadas las restricciones, en cada una de las secciones, siento que esto tiene sentido si está un poco anidado.

Sin embargo, mi dificultad viene si quiero enumerar ( GET) a todos los empleados de todas las empresas.

El patrón de recursos para eso se correlacionaría más estrechamente con /employees(La colección de todos los empleados)

¿Eso significa que debería haberlo hecho /employees/{empId}también porque, de ser así, hay dos URI para obtener el mismo recurso?

O tal vez todo el esquema debería ser aplanado, pero eso significaría que los empleados son un objeto anidado de nivel superior.

En un nivel básico, /employees/?company={companyId}&department={deptId}devuelve exactamente la misma vista de los empleados que el patrón más profundamente anidado.

¿Cuál es la mejor práctica para los patrones de URL donde los recursos son propiedad de otros recursos pero deberían poder consultarse por separado?

Lo que has hecho es correcto. En general, puede haber muchos URI para el mismo recurso; no hay reglas que indiquen que no debe hacer eso.

Y, en general, es posible que deba acceder a los elementos directamente o como un subconjunto de otra cosa, por lo que su estructura tiene sentido para mí.

Solo porque los empleados son accesibles bajo el departamento:

company/{companyid}/department/{departmentid}/employees

No significa que no puedan ser accesibles bajo la compañía también:

company/{companyid}/employees

Lo que devolvería a los empleados de esa empresa. Depende de lo que necesite su cliente consumidor: para eso debe estar diseñando.

Pero espero que todos los manejadores de URL utilicen el mismo código de respaldo para satisfacer las solicitudes, de modo que no esté duplicando el código.

He probado ambas estrategias de diseño: puntos finales anidados y no anidados. He encontrado que:

1. Si el recurso anidado tiene una clave primaria y no tiene su clave primaria principal, la estructura anidada requiere que la obtenga, aunque el sistema no la requiera realmente.

2. Los puntos finales anidados generalmente requieren puntos finales redundantes. En otras palabras, la mayoría de las veces necesitará el punto final adicional / empleados para que pueda obtener una lista de empleados en todos los departamentos. Si tienes / empleados, ¿qué es exactamente lo que te compran / compañías / departamentos / empleados?

3. Los puntos finales de anidación no evolucionan tan bien. Por ejemplo, es posible que no necesite buscar empleados ahora, pero podría hacerlo más tarde y si tiene una estructura anidada, no tiene más remedio que agregar otro punto final. Con un diseño no anidado, simplemente agrega más parámetros, lo cual es más simple.

4. a veces un recurso puede tener múltiples tipos de padres. Resultando en múltiples puntos finales que devuelven el mismo recurso.

5. los puntos finales redundantes hacen que los documentos sean más difíciles de escribir y también hacen que la API sea más difícil de aprender.

En resumen, el diseño no anidado parece permitir un esquema de punto final más flexible y simple.

Moví lo que hice de la pregunta a una respuesta donde es probable que más personas lo vean.

Lo que he hecho es tener los puntos finales de creación en el punto final anidado. El punto final canónico para modificar o consultar un elemento no está en el recurso anidado .

Entonces, en este ejemplo (solo enumerando los puntos finales que cambian un recurso)

• POST /companies/ crea una nueva compañía devuelve un enlace a la compañía creada.
• POST /companies/{companyId}/departments cuando se crea un departamento, el nuevo departamento devuelve un enlace a /departments/{departmentId}
• PUT /departments/{departmentId} modifica un departamento
• POST /departments/{deparmentId}/employees crea un nuevo empleado devuelve un enlace a /employees/{employeeId}

Por lo tanto, hay recursos de nivel raíz para cada una de las colecciones. Sin embargo, la creación está en el objeto propietario .

He leído todas las respuestas anteriores, pero parece que no tienen una estrategia común. Encontré un buen artículo sobre las mejores prácticas en Design API de Microsoft Documents . Creo que deberías referirte.

En sistemas más complejos, puede ser tentador proporcionar URI que permitan a un cliente navegar a través de varios niveles de relaciones, como /customers/1/orders/99/products.Sin embargo, este nivel de complejidad puede ser difícil de mantener y es inflexible si las relaciones entre recursos cambian en el futuro. En su lugar, trate de mantener los URI relativamente simples . Una vez que una aplicación tiene una referencia a un recurso, debería ser posible utilizar esta referencia para buscar elementos relacionados con ese recurso. La consulta anterior se puede reemplazar con el URI /customers/1/orderspara encontrar todos los pedidos para el cliente 1 y luego /orders/99/productspara encontrar los productos en este orden.

.

Propina

Evite requerir URI de recursos más complejos que collection/item/collection.

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 ")

No estoy de acuerdo con este tipo de camino

GET /companies/{companyId}/departments

Si desea obtener departamentos, creo que es mejor usar un recurso / departamentos

GET /departments?companyId=123

Supongo que tiene una companiestabla y una departmentstabla, luego clases para mapearlas en el lenguaje de programación que usa. También supongo que los departamentos podrían estar vinculados a otras entidades que no sean empresas, por lo que un recurso / departamentos es sencillo, es conveniente tener recursos asignados a tablas y tampoco necesita tantos puntos finales ya que puede reutilizar

GET /departments?companyId=123

para cualquier tipo de búsqueda, por ejemplo

GET /departments?name=xxx
GET /departments?companyId=123&name=xxx
etc.

Si desea crear un departamento, el

POST /departments

se debe utilizar el recurso y el cuerpo de la solicitud debe contener el ID de la empresa (si el departamento puede vincularse a una sola empresa)

Rails proporciona una solución a esto: anidamiento superficial .

Creo que esto es bueno porque cuando se trata directamente con un recurso conocido, no hay necesidad de usar rutas anidadas, como se ha discutido en otras respuestas aquí.