Como projetar terminais de API para postar um objeto filho e para obter todos os filhos de todos os pais?

5

Por exemplo, eu 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}

Como para 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:

  1. (eu vi em alguma API do google) use "-" em vez disso e analise-o como "all":

/clients/-/reports

Isso mantém o mesmo formato de ponto de extremidade, mas parece um pouco unusal, não é possível encontrar qualquer rfc que sugira isso.

  1. Crie um endpoint separado apenas para todos os relatórios:

/reports

Mas para obter os Relatórios do cliente, ainda é:

/clients/{client_id}/reports

  1. Refaça os pontos de extremidade para tornar "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 ponto de extremidade para postar um relatório para um cliente específico, ele pode parecer feio, porque será uma solicitação POST com um parâmetro na URL.

Existe alguma outra sugestão de ideias?

    
por Yann 24.08.2017 / 16:57
fonte

2 respostas

2

But how should look an endpoint for getting all the Reports of all the Clients to keep API consistent and well designed.

Antes de mais nada, lembre-se de que não há regras de ouro para modelar APIs RESTful. Tudo o que temos são melhores práticas e convenções. Dito isto, a resposta provável é, como de costume, escolher aquele que melhor atenda às suas necessidades e, neste caso, aquele que melhor expressa seu modelo.

Portanto, verifique as três opções a partir da expressividade.

# 1 A notação "-"

Esta é uma ideia brilhante. Isso nos permite expressar a condição todo o reports que pertence a clients . Está estreitando a "consulta" para um conjunto específico de relatórios (aqueles localizados dentro do limite clients ).

Ele mantém a noção de hierarquia (pertencente) o tempo todo, portanto, se reports puder ser encontrado em locais diferentes, essa notação será importante. Por exemplo:

  • Todos os relatórios que pertencem aos clientes /clients/-/reports
  • Todos os relatórios que pertencem aos departamentos /departments/-/reports
  • Todos os relatórios que pertencem aos funcionários /employees/-/reports

No entanto, para recuperar todos os relatórios disponíveis no sistema, manter a hierarquia não oferece 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 parece mais razoável para mim.

O novo URI ( /reports ) também deixa aberta a possibilidade de um gerenciamento de relatórios . No entanto, não precisamos fornecer um suporte REST completo se não considerarmos necessário. Por exemplo, você declarou Make a separate endpoint just for all the reports . Tudo bem, você só precisa implementar GET e talvez alguns filtros para consulta e pronto.

Observe que você ainda pode fazer isso /reports?client={client_id} . Ter um URI diferente para o mesmo recurso é bom. Alguns artigos que eu li chamariam isso robustez .

# 3 Revertendo a hierarquia

Tenho a sensação de que essa abordagem não atende às suas expectativas. Além disso, eu acho que isso o levará ao ponto de partida.

Conclusões

Observe que # 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º 2.

1: é equivalente a /clients/-/reports , suponho

    
por 24.08.2017 / 22:11
fonte
0

Os padrões de design da API do Google sugerem o uso de '-' neste cenário.

GET /clients/-/reports

Fonte:

link

    
por 24.08.2017 / 17:34
fonte