Práticas recomendadas da API REST: args na string de consulta vs no corpo da solicitação

Uma API REST pode ter argumentos em vários lugares:

1. No corpo da solicitação - como parte de um corpo json ou outro tipo MIME
2. Na string de consulta - por exemplo/api/resource?p1=v1&p2=v2
3. Como parte do caminho do URL - por exemplo/api/resource/v1/v2

Quais são as melhores práticas e considerações para escolher entre 1 e 2 acima?
2 vs 3 é abordado aqui .

Quais são as melhores práticas e considerações para escolher entre 1 e 2 acima?

Normalmente, o corpo do conteúdo é usado para os dados que devem ser carregados / baixados de / para o servidor e os parâmetros de consulta são usados ​​para especificar os dados exatos solicitados. Por exemplo, quando você faz upload de um arquivo, especifica o nome, tipo MIME, etc. no corpo, mas quando busca uma lista de arquivos, você pode usar os parâmetros de consulta para filtrar a lista por alguma propriedade dos arquivos. Em geral, os parâmetros da consulta são propriedade da consulta e não dos dados.

Claro que esta não é uma regra estrita - você pode implementá-la da maneira que achar mais apropriada / adequada para você.

Você também pode querer verificar o artigo da Wikipedia sobre string de consulta , especialmente os dois primeiros parágrafos.

Presumo que você esteja falando sobre solicitações POST / PUT. Semanticamente, o corpo da solicitação deve conter os dados que você está postando ou corrigindo.

A string de consulta, como parte da URL (um URI), está lá para identificar qual recurso você está postando ou corrigindo.

Você pediu as melhores práticas, a semântica seguinte é minha. É claro que usar suas regras básicas deve funcionar, especialmente se a estrutura da web que você usa abstrai isso em parâmetros .

Você mais sabe:

• Alguns servidores da web têm limites para o comprimento do URI.
• Você pode enviar parâmetros dentro do corpo da solicitação com CURL.
• O local para o qual você envia os dados não deve afetar a depuração.

A seguir estão minhas regras básicas ...

Quando usar o corpo:

• Quando os argumentos não têm uma chave simples: estrutura de valor
• Se os valores não forem legíveis por humanos, como dados binários serializados
• Quando você tem um grande número de argumentos

Quando usar a string de consulta:

• Quando os argumentos são tais que você deseja vê-los durante a depuração
• Quando você quiser poder chamá-los manualmente durante o desenvolvimento do código, por exemplo, com curl
• Quando os argumentos são comuns em muitos serviços da web
• Quando você já está enviando um tipo de conteúdo diferente, como application/octet-stream

Observe que você pode misturar e combinar - coloque os mais comuns, aqueles que devem ser depurados na string de consulta, e jogue todo o resto no json.