Quais são as práticas recomendadas para recursos aninhados REST?

Tanto quanto posso dizer, cada recurso individual deve ter apenas um caminho canônico . Portanto, no exemplo a seguir, quais seriam os bons padrões de URL?

Tomemos como exemplo uma representação restante das empresas. Neste exemplo hipotético, cada empresa possui 0 ou mais departamentos e cada departamento possui 0 ou mais funcionários.

Um departamento não pode existir sem uma empresa associada.

Um funcionário não pode existir sem um departamento associado.

Agora eu consideraria a representação natural dos padrões de recursos.

• /companies Uma coleção de empresas - aceita colocar para uma nova empresa. Obter para toda a coleção.
• /companies/{companyId}Uma empresa individual. Aceita GET, PUT e DELETE
• /companies/{companyId}/departmentsAceita POST para um novo item. (Cria um departamento dentro da empresa.)
• /companies/{companyId}/departments/{departmentId}/
• /companies/{companyId}/departments/{departmentId}/employees
• /companies/{companyId}/departments/{departmentId}/employees/{empId}

Dadas as restrições, em cada uma das seções, sinto que isso faz sentido se um pouco profundamente aninhado.

No entanto, minha dificuldade surge se eu quiser listar ( GET) todos os funcionários em todas as empresas.

O padrão de recursos para o qual seria mais próximo /employees(A coleção de todos os funcionários)

Isso significa que eu deveria ter /employees/{empId}também porque, nesse caso, existem dois URIs para obter o mesmo recurso?

Ou talvez o esquema inteiro deva ser achatado, mas isso significa que os funcionários são um objeto de nível superior aninhado.

Em um nível básico, /employees/?company={companyId}&department={deptId}retorna exatamente a mesma visão dos funcionários que o padrão mais profundamente aninhado.

Qual é a melhor prática para padrões de URL em que os recursos pertencem a outros recursos, mas devem ser consultados separadamente?

O que você fez está correto. Em geral, pode haver muitos URIs para o mesmo recurso - não há regras que digam que você não deve fazer isso.

E geralmente, você pode precisar acessar itens diretamente ou como um subconjunto de outra coisa - para que sua estrutura faça sentido para mim.

Só porque os funcionários estão acessíveis no departamento:

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

Não significa que eles também não possam ser acessíveis na empresa:

company/{companyid}/employees

O que retornaria funcionários para essa empresa. Depende do que é necessário para o seu cliente consumidor - é para isso que você deve projetar.

Mas espero que todos os manipuladores de URLs usem o mesmo código de suporte para atender às solicitações, para que você não esteja duplicando o código.

Eu tentei as duas estratégias de design - pontos de extremidade aninhados e não aninhados. Eu descobri que:

1. se o recurso aninhado tiver uma chave primária e você não tiver sua chave primária pai, a estrutura aninhada exigirá que você a obtenha, mesmo que o sistema não a exija.

2. pontos de extremidade aninhados geralmente requerem pontos de extremidade redundantes. Em outras palavras, você precisará mais frequentemente do ponto de extremidade / funcionários para poder obter uma lista de funcionários entre os departamentos. Se você possui / funcionários, o que exatamente / empresas / departamentos / funcionários compram para você?

3. pontos finais de aninhamento não evoluem tão bem. Por exemplo, talvez você não precise procurar funcionários agora, mas pode precisar mais tarde e, se tiver uma estrutura aninhada, não terá outra opção a não ser adicionar outro ponto de extremidade. Com um design não aninhado, você apenas adiciona mais parâmetros, o que é mais simples.

4. Às vezes, um recurso pode ter vários tipos de pais. Resultando em vários pontos de extremidade, todos retornando o mesmo recurso.

5. pontos finais redundantes tornam os documentos mais difíceis de escrever e também tornam a API mais difícil de aprender.

Em resumo, o design não aninhado parece permitir um esquema de terminal mais flexível e mais simples.

Mudei o que fiz da pergunta para uma resposta em que mais pessoas provavelmente o verão.

O que fiz foi ter os pontos de extremidade de criação no ponto de extremidade aninhado. O ponto de extremidade canônico para modificar ou consultar um item não está no recurso aninhado .

Portanto, neste exemplo (apenas listando os pontos de extremidade que alteram um recurso)

• POST /companies/ cria uma nova empresa retorna um link para a empresa criada.
• POST /companies/{companyId}/departments quando um departamento é criado, o novo departamento retorna um link para /departments/{departmentId}
• PUT /departments/{departmentId} modifica um departamento
• POST /departments/{deparmentId}/employees cria um novo funcionário retorna um link para /employees/{employeeId}

Portanto, existem recursos no nível raiz para cada uma das coleções. No entanto, a criação está no objeto proprietário .

Eu li todas as respostas acima, mas parece que elas não têm uma estratégia comum. Encontrei um bom artigo sobre as práticas recomendadas na Design API da Microsoft Documents . Eu acho que você deveria se referir.

Em sistemas mais complexos, pode ser tentador fornecer URIs que permitem que um cliente navegue por vários níveis de relacionamentos, como /customers/1/orders/99/products.No entanto, esse nível de complexidade pode ser difícil de manter e é inflexível se os relacionamentos entre recursos mudarem no futuro. Em vez disso, tente manter os URIs relativamente simples . Depois que um aplicativo tem uma referência a um recurso, deve ser possível usá-lo para encontrar itens relacionados a esse recurso. A consulta anterior pode ser substituída pelo URI /customers/1/orderspara localizar todos os pedidos do cliente 1 e, em seguida, /orders/99/productsencontrar os produtos nesse pedido.

.

Dica

Evite exigir URIs de recursos mais complexos que collection/item/collection.

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

Eu discordo deste tipo de caminho

GET /companies/{companyId}/departments

Se você deseja obter departamentos, acho melhor usar um recurso / departamentos

GET /departments?companyId=123

Suponho que você tenha uma companiestabela e uma departmentstabela e depois classes para mapeá-las na linguagem de programação usada. Também presumo que os departamentos possam ser anexados a outras entidades que não as empresas; portanto, um recurso / departamentos é direto, é conveniente ter recursos mapeados para tabelas e você também não precisa de muitos pontos de extremidade, pois pode reutilizar

GET /departments?companyId=123

para qualquer tipo de pesquisa, por exemplo

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

Se você deseja criar um departamento, o

POST /departments

o recurso deve ser usado e o corpo da solicitação deve conter o ID da empresa (se o departamento puder ser vinculado a apenas uma empresa).

O Rails fornece uma solução para isso: aninhamento superficial .

Eu acho que isso é bom porque, quando você lida diretamente com um recurso conhecido, não há necessidade de usar rotas aninhadas, conforme discutido em outras respostas aqui.