Uma API HTTP sempre deve retornar um corpo?

Existe algum tipo de padrão em relação às respostas da API HTTP?

Depois de ler este tópico do discurso , comecei a me perguntar. Estamos desenvolvendo nossa API HTTP JSON pública no meu trabalho e não retornamos nada quando não é estritamente necessário (por exemplo, um PUT para / resource / {id} retorna apenas 200 quando OK ou o código 4XX ou 5XX correspondente, mas não JSON)

Devemos retornar um genérico {"success":true}como eles discutem no link acima, ou está correto devolver um corpo "vazio" e lidar com tudo com códigos de resposta http?

Em relação ao PUT, mas também se aplica ao POST. A seção de especificação HTTP 9 é um pouco vazia de regras ou mesmo conselhos (DEVE) quando se trata do cenário que você está descrevendo. A linha relevante para sua pergunta é abordada mais de perto por:

Se um novo recurso for criado, o servidor de origem DEVE informar o agente do usuário através da resposta 201 (Criada). Se um recurso existente for modificado, os códigos de resposta 200 (OK) ou 204 (sem conteúdo) DEVEM ser enviados para indicar a conclusão bem-sucedida da solicitação.

Eu não acho que perderia o sono por isso, mas perguntaria: o que você ganha adicionando a parte do JSON à resposta? Você acabou de aumentar (OK, pode ser um exagero!) A resposta repetindo com menos precisão o que o código de status já deveria ter lhe contado. Se o seu PUT resultou em um novo objeto retornar 201 (como é a intenção do PUT), se ele atualizou um objeto, retorne 204.

Aliás, a API de lado, em vez de 200, se você não retornar nada, use 204.

Supondo que você esteja desenvolvendo um conjunto de interfaces RESTful, não existe um padrão em si; portanto, faça o que fizer, documente-o bem, forneça exemplos e tudo ficará bem.

O padrão HTTP base não exige que haja um documento retornado com uma resposta. Por uma questão de economia, quando um status HTTP transmite tudo o que é necessário, o corpo seria um desperdício. No entanto, existem padrões criados no HTTP que adicionam novas regras.

Há um padrão aberto da API JSON que especifica:

• Um objeto JSON DEVE estar na raiz de todos os documentos de resposta da API JSON . (itálico representa o que adicionei para esclarecer o texto)

Infelizmente, o padrão não especifica como representar um documento vazio e é um trabalho em andamento. Na melhor das hipóteses, eu o usaria como orientação.

Alguns aplicativos (como ElasticSearch ) fornecem uma API JSON completa e sempre possuem alguns metadados para que você possa ter uma idéia melhor de como o servidor está gerenciando seus dados. O objeto de resposta padrão informa sobre a integridade do índice, se a solicitação resultou em um erro, quantos nós foram afetados etc. O ElasticSearch usa "application / json" para o tipo MIME, portanto é improvável que eles estejam aplicando as diretrizes em o padrão jsonapi.org.

As estruturas JQuery e Javascript semelhantes assumem que sempre haverá um documento. A questão é quanta verificação de erro você deseja impor aos seus consumidores de API? Se você criar um formato padrão para todas as respostas que são estendidas apenas com base no tipo de solicitação, satisfaz a necessidade de um documento de retorno e pode facilitar a depuração mais fácil pelos consumidores da API.

Não, por exemplo, para 204 respostas, não devemos incluir o corpo da mensagem. {success | status | isSuccessful: true} é redundante.

Na prática (ou devo dizer na versão posterior do jquery), a resposta vazia para o tipo de conteúdo application / json gera erro. Eu meio que entendo o argumento de que, por ser application / json, ele deve ter um corpo json válido. Portanto, a resposta vazia para o tipo de conteúdo application / json seria 'null' ou '{}', que são json válidos.

Existe outra maneira que deve funcionar para o jquery, que não está retornando application / json para respostas vazias. Basta usar texto / simples ou algo assim e verifique se o cliente pode lidar com esse tipo.

Nota : Só me lembro de 204 por proibir explicitamente o retorno do corpo da mensagem. O que descobrimos é que nem sempre podemos usar 204. O problema é o MSIE soltar o cabeçalho de resposta para 204 respostas, portanto, não há conteúdo e cabeçalhos, o que é ruim. Como muitos estão usando o MSIE, tivemos que alterá-lo para o status 200.

Não, mas isso ajudará na consistência do seu código. Também é bom para fins de depuração. Também será uma grande ajuda na manutenção do site. Lembre-se disto: o código de erro é para a máquina, a mensagem de erro é para humanos. Então, estou sugerindo que você use um corpo de resposta. De qualquer forma, seu efeito negativo é mínimo (apenas alguns bytes enviados pela rede) em comparação com seus benefícios. Outra coisa, também evitará que você esqueça de escrever um corpo da mensagem quando necessário.

Eu não retornaria um status simplesmente de sucesso na resposta, o código de erro http indica apenas sucesso ou erro. Incluiria apenas o uso da resposta em si para adicionar informações detalhadas sobre erros, como códigos de erro específicos do aplicativo ou mensagens de erro.

Para solicitações PUT, PATCH e POST, você normalmente retorna o estado, retorna o estado do recurso após a solicitação ter sido aplicada, não uma resposta vazia.

Para solicitações POST que representam uma ação em vez de simplesmente criar um recurso (não muito RESTful, mas ainda útil na prática), que não possui dados úteis a serem retornados, eu retornaria uma resposta consistindo em um objeto json vazio, ou seja {}. Dessa forma, o cliente obtém uma resposta válida e é improvável que a adição de algumas informações mais tarde a interrompa.

Para solicitações DELETE retornando 204 e um corpo vazio é bastante comum, o que faz sentido, pois o recurso não existe posteriormente.

Eu sugeriria retornar apenas o que é necessário + um pouco de esclarecimento.

Por exemplo, dependendo de como sua API deve ser usada, você pode incluir uma cópia do objeto, como existe após ser salva.

Portanto, um POST de {key: 123} pode retornar {key: 123, foo: 'bar'}.

A idéia básica é que é melhor retornar o objeto do que ter que consultá-lo novamente.

Dito isto, os consumidores da sua API não precisam do objeto, não há necessidade de devolvê-lo.

Eu normalmente retorno {success: true} ou algo parecido, quando não há um objeto necessário no POST PUT e PATCH, porque facilita o recebimento. Dito isso, é melhor 99% do tempo retornar a representação salva do objeto, é raro que eles não precisem, e é "mais barato" enviar tudo em uma solicitação e depois em duas.

Para ser específico, em um laboratório, é perfeitamente adequado lidar com tudo com apenas códigos de status. No mundo real, é muito melhor retornar alguns dados, mesmo que redundantes, para que os consumidores de API possam entender facilmente o que você está tentando dizer.

O retorno de 200 {success: true} permite que as pessoas escrevam código nos dois sentidos:

if response.code == 200
  do stuff
end

e

if response.body.success
  do stuff
end

Além disso, não é tão difícil de fazer do seu lado.

Por fim, (desculpe pela estrutura de respostas do cocô), fornecendo uma API JSON pública para você abrir mão de muito controle sobre como será usado. Alguns clientes podem reagir de maneira diferente a diferentes organismos (ou a falta deles) ou a códigos de status.