'Melhor' prática para uma resposta tranquila ao POST

Portanto, nada de novo aqui, estou apenas tentando obter algum esclarecimento e parece que não consigo encontrar nenhum em outros posts.

Estou criando um novo recurso com repulsa, digamos:

/books (POST)

com um corpo:

{
  title: 'The Lion, the Witch and the Wardrobe',
  author: 'C. S. Lewis'
}

Eu sei que devo retornar um 201 (criado) com um cabeçalho de localização do novo recurso:

Location: /books/12345

A pergunta que não consigo responder por mim mesma é o que o servidor deve retornar no corpo.

Eu sempre fiz esse tipo de resposta:

{
  id: 12345,
  title: 'The Lion, the Witch and the Wardrobe',
  author: 'C. S. Lewis'
}

Eu fiz isso por alguns motivos:

1. Eu escrevi api para estruturas de front-end como angularjs. No meu caso particular, estou usando recursos angulares e geralmente preciso apenas da identificação do recurso para localizá-lo. Se eu não retornasse o ID no corpo da resposta, seria necessário analisá-lo no cabeçalho Location.
2. Em um GET de todos os livros, geralmente retorno o objeto inteiro, não apenas o ID. Nesse sentido, meu código de cliente não precisa diferenciar de onde obter o ID (cabeçalho ou corpo do local).

Agora eu sei que estou realmente na área cinzenta aqui, mas a maioria das pessoas está dizendo que devolver todo o recurso é uma prática 'ruim'. Mas e se o servidor alterar / adicionar informações ao recurso. Definitivamente adiciona o ID, mas também pode adicionar outras coisas, como um carimbo de data / hora. No caso de eu não retornar o recurso inteiro, é realmente melhor fazer um POST, retornar o ID e fazer com que o cliente execute um GET para obter o novo recurso.

Retornar o objeto inteiro em uma atualização não parece muito relevante, mas mal consigo entender por que retornar o objeto inteiro quando ele é criado seria uma prática ruim em um caso de uso normal. Isso seria útil pelo menos para obter o ID facilmente e obter os registros de data e hora, quando relevante. Na verdade, esse é o comportamento padrão obtido quando se anda com o Rails.

Realmente não vejo nenhuma vantagem em retornar apenas o ID e fazer uma solicitação GET depois, para obter os dados que você poderia obter com o seu POST inicial.

De qualquer forma, desde que sua API seja consistente, acho que você deve escolher o padrão que melhor se adapte às suas necessidades. Não há nenhuma maneira correta de como criar uma API REST, imo.

O retorno do novo objeto se encaixa no princípio REST de "Interface Uniforme - Manipulação de Recursos por meio de Representações". O objeto completo é a representação do novo estado do objeto que foi criado.

Há uma referência realmente excelente para o design da API, aqui: Práticas recomendadas para projetar uma API RESTful pragmática

Inclui uma resposta para sua pergunta aqui: Atualizações e criação devem retornar uma representação de recurso

Diz:

Para impedir que um consumidor da API precise acessar a API novamente para obter uma representação atualizada, faça com que a API retorne a representação atualizada (ou criada) como parte da resposta.

Parece bem pragmático para mim e se encaixa no princípio REST que mencionei acima.