Por exemplo, tenho entidades: Cliente, Relatório. O cliente pode ter muitos relatórios e acho que o ponto final de um único gerenciamento de relatórios deve ser aninhado assim:
/clients/{client_id}/reports/{report_id}
Quanto a todos os relatórios de um cliente, o enpoint é esperado:
/clients/{client_id}/reports
Mas como deve ser um ponto de extremidade para obter todos os relatórios de todos os clientes para manter a API consistente e bem projetada.
Minhas abordagens:
- (Eu vi em algumas APIs do Google) use "-" em vez dele e analise-o como "todos":
/clients/-/reports
Isso mantém o formato do ponto final o mesmo, mas parece um pouco incomum, não consegue encontrar nenhum rfc que sugira esse caminho.
- Faça um ponto de extremidade separado apenas para todos os relatórios:
/reports
Mas, para obter os relatórios do cliente, ainda é:
/clients/{client_id}/reports
- Refatorar pontos de extremidade para tornar o "cliente" não um pai, mas apenas um parâmetro de filtro:
/reports?client={client_id}
- relatórios de um cliente
/reports
- relatórios de todo o cliente
No caso de adicionar um novo terminal para postar um relatório para um cliente específico, pode parecer feio, porque será uma solicitação POST com um parâmetro na URL.
Existem outras sugestões de idéias?
fonte
Respostas:
Antes de mais nada, lembre-se de que não há regras de ouro para modelar APIs RESTful. Tudo o que temos são boas práticas e convenções. Dito isto, a resposta provável é, como sempre, escolher a que melhor atende aos seus requisitos e, nesse caso, a que melhor expressa seu modelo.
Portanto, verifique as três opções da expressividade.
# 1 A notação "-"
Esta é uma ideia brilhante. Permite-nos expressar a condição a
reports
que tudo pertenceclients
. Está restringindo a "consulta" a um conjunto específico de relatórios (aqueles localizados dentro dosclients
limites).Mantém a noção de hierarquia (pertencente) o tempo todo; portanto, se
reports
puder ser encontrada em locais diferentes, essa notação é importante. Por exemplo:/clients/-/reports
/departments/-/reports
/employees/-/reports
No entanto, para recuperar todos os relatórios disponíveis no sistema, manter a hierarquia não fornece nenhuma vantagem valiosa sobre a próxima opção.
# 2 URIs diferentes
Se não precisarmos expressar limites / contextos / hierarquia no momento de recuperar todos os relatórios disponíveis , essa abordagem me parecerá mais razoável.
O novo URI (
/reports
) também deixa em aberto a possibilidade de um gerenciamento de relatórios . No entanto, não precisamos fornecer um suporte RESTful completo, se não considerarmos necessário. Por exemplo, você declarouMake a separate endpoint just for all the reports
. Tudo bem, você só precisa implementarGET
e talvez alguns filtros para consulta e é isso.Observe que você ainda pode fazer isso
/reports?client={client_id}
. Ter um URI diferente para o mesmo recurso é bom. Alguns artigos que li chamariam isso de robustez .# 3 Revertendo a hierarquia
Tenho a sensação de que essa abordagem não atende às suas expectativas. Além disso, acho que isso o levará ao ponto de partida.
Conclusões
Observe que os nºs 1 e 2 não são mutuamente exclusivos. Nós podemos implementar ambos. Dada a situação real e de acordo com as premissas do OP, eu implementaria apenas o número 2.
1: é equivalente a
/clients/-/reports
eu achofonte
Os padrões de design da API do Google sugerem o uso de '-' nesse cenário.
Fonte:
https://cloud.google.com/apis/design/design_patterns#list_sub-collections
fonte
/client/{client_id}/report/{report_id}
e/clients/report/{report_id}
/reports
?/clients...
e/reports
.