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

125

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 .

Jonathan
fonte
Isso responde sua pergunta? Práticas recomendadas da API REST: Onde colocar os parâmetros?
Steve Chambers
Além do acima, que tal usar o cabeçalho?
variável de

Respostas:

39

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.

stan0
fonte
1
Uma conclusão razoável para sua análise acima é que as operações idempotentes são mais bem mantidas nas strings de consulta de url e CRUD é melhor mantido em corpos de resposta estritamente digitados, o que essencialmente tira proveito do SOP e evita formas muito básicas de ataques de engenharia social / phishing
Rice
15

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.
Leonel Galán
fonte
6

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.

Jonathan
fonte
34
Selecionar como estruturar sua API com base na conveniência de desenvolvimento não é uma boa prática.
Eric Stein
1
Como @EricStein disse, você entendeu ao contrário.
DanMan
20
Pessoal, a razão pela qual fiz a pergunta é para obter a resposta certa. Vá em frente, escreva uma resposta e eu removerei minha falha. @EricStein
Jonathan de
4
Apis @Jonathan que são fáceis de consumir por mãos humanas quase sempre são boas apis. Parabéns por chamar o KISS com precisão
Chris Marisic
1
@AkshayHiremath Ele está se referindo ao fato de que você pode estar enviando outra coisa no corpo, por exemplo, se você enviou um cabeçalho ContentType como "imagem / jpeg", você precisa que o corpo da sua mensagem contenha os dados jpeg e não possa incluir mais nada em it
Shayaan