Cree una solicitud con POST, cuyos códigos de respuesta 200 o 201 y contenido

Supongamos que escribo un servicio REST cuya intención es agregar un nuevo elemento de datos a un sistema.

Planeo PUBLICAR en

http://myhost/serviceX/someResources

Supongamos que funciona, ¿qué código de respuesta debo usar? Y qué contenido podría devolver.

Estoy mirando las definiciones de los códigos de respuesta HTTP y veo estas posibilidades:

200: Devuelve una entidad que describe o contiene el resultado de la acción;

201: que significa CREADO. Significado * La solicitud se ha cumplido y se ha creado un nuevo recurso. El recurso recién creado puede ser referenciado por los URI devueltos en la entidad de la respuesta, con el URI más específico para el recurso dado por un campo de encabezado de Ubicación. La respuesta DEBE incluir una entidad que contenga una lista de características de recursos y ubicaciones de las cuales el usuario o agente de usuario puede elegir la más apropiada. El formato de entidad se especifica por el tipo de medio dado en el campo de encabezado Tipo de contenido. * *

Este último suena más en línea con la especificación Http, pero no estoy del todo claro qué

La respuesta DEBE incluir una entidad que contenga una lista de características y ubicaciones del recurso

medio.

Recomendaciones? Interpretaciones?

La idea es que el cuerpo de respuesta te dé una página que te vincule a la cosa:

201 Creado

El código de estado 201 (Creado) indica que la solicitud se ha cumplido y se ha creado uno o más recursos nuevos. El recurso primario creado por la solicitud se identifica mediante un campo de encabezado de Ubicación en la respuesta o, si no se recibe ningún campo de Ubicación, mediante el URI de solicitud efectivo.

Esto significa que se incluiría una Locationen la respuesta de cabecera que da a la URL de donde se puede encontrar la recién creada cosa :

HTTP/1.1 201 Created
Date: Sat, 02 Apr 2016 12:22:40 GMT
Location: http://stackoverflow.com/a/36373586/12597

Cuerpo de respuesta

Luego mencionan lo que debe incluir en el cuerpo de respuesta :

La carga útil de 201 respuestas generalmente describe y enlaza a los recursos creados.

Para los humanos que usan el navegador, les das algo que pueden mirar y hacer clic para acceder a su recurso recién creado:

HTTP/1.1 201 Created
Date: Sat, 02 Apr 2016 12:22:40 GMT
Location: http://stackoverflow.com/a/36373586/12597
Content-Type: text/html

Your answer has been saved! 
Click <A href="https://stackoverflow.com/a/36373586/12597">here</A> to view it.

Si la página solo será utilizada por un robot, tiene sentido que la respuesta sea legible por computadora:

HTTP/1.1 201 Created
Date: Sat, 02 Apr 2016 12:22:40 GMT
Location: http://stackoverflow.com/a/36373586/12597
Content-Type: application/xml

<createdResources>
   <questionID>1860645</questionID>
   <answerID>36373586</answerID>
   <primary>/a/36373586/12597</primary>
   <additional>
      <resource>http://stackoverflow.com/questions/1860645/create-request-with-post-which-response-codes-200-or-201-and-content/36373586#36373586</resource>
      <resource>http://stackoverflow.com/a/1962757/12597</resource>
   </additional>
</createdResource>

O, si lo prefieres:

HTTP/1.1 201 Created
Date: Sat, 02 Apr 2016 12:22:40 GMT
Location: http://stackoverflow.com/a/36373586/12597
Content-Type: application/json

{ 
   "questionID": 1860645, 
   "answerID": 36373586,
   "primary": "/a/36373586/12597",
   "additional": [
      "http://stackoverflow.com/questions/1860645/create-request-with-post-which-response-codes-200-or-201-and-content/36373586#36373586",
      "http://stackoverflow.com/a/36373586/12597"
   ]
}

La respuesta es totalmente suya; es arbitrariamente lo que te gustaría.

Caché amigable

Finalmente, está la optimización de que puedo almacenar previamente en caché el recurso creado (porque ya tengo el contenido; lo acabo de cargar). El servidor puede devolver una fecha o ETag que puedo almacenar con el contenido que acabo de cargar:

Consulte la Sección 7.2 para una discusión sobre el significado y el propósito de los campos de encabezado del validador, como ETag y Last-Modified, en una respuesta 201.

HTTP/1.1 201 Created
Date: Sat, 02 Apr 2016 12:22:40 GMT
Location: http://stackoverflow.com/a/23704283/12597
Content-Type: text/html
ETag: JF2CA53BOMQGU5LTOQQGC3RAMV4GC3LQNRSS4
Last-Modified: Sat, 02 Apr 2016 12:22:39 GMT 

Your answer has been saved! 
Click <A href="https://stackoverflow.com/a/36373586/12597">here</A> to view it.

Y ETags son valores puramente arbitrarios. Lo único que importa es que sean diferentes cuando un recurso cambia (y las memorias caché deben actualizarse). El ETag suele ser un hash (por ejemplo, SHA2). Pero puede ser una base de datos rowversiono un número de revisión incremental. Cualquier cosa que cambie cuando la cosa cambie.

Creo que la API REST de atompub es un gran ejemplo de un servicio tranquilo. Vea el fragmento a continuación de la especificación atompub:

POST /edit/ HTTP/1.1
Host: example.org
User-Agent: Thingio/1.0
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Type: application/atom+xml;type=entry
Content-Length: nnn
Slug: First Post

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>Atom-Powered Robots Run Amok</title>
  <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
  <updated>2003-12-13T18:30:02Z</updated>
  <author><name>John Doe</name></author>
  <content>Some text.</content>
</entry>

El servidor señala una creación exitosa con un código de estado de 201. La respuesta incluye un encabezado de ubicación que indica el URI de entrada de miembro de la entrada de átomo y una representación de esa entrada en el cuerpo de la respuesta.

HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml;type=entry;charset="utf-8"
Location: http://example.org/edit/first-post.atom
ETag: "c180de84f991g8"  

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>Atom-Powered Robots Run Amok</title>
  <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
  <updated>2003-12-13T18:30:02Z</updated>
  <author><name>John Doe</name></author>
  <content>Some text.</content>
  <link rel="edit"
      href="http://example.org/edit/first-post.atom"/>
</entry>

Es posible que la Entrada creada y devuelta por la Colección no coincida con la Entrada PUBLICADA por el cliente. Un servidor PUEDE cambiar los valores de varios elementos en la Entrada, como los valores atom: id, atom: updated y atom: author, y PUEDE elegir eliminar o agregar otros elementos y atributos, o cambiar el contenido del elemento y los valores de los atributos.

En pocas palabras:

• 200 cuando se crea y devuelve un objeto
• 201 cuando se crea un objeto pero solo se devuelve su referencia (como un ID o un enlace)

Consulte HTTP: Definiciones de métodos: POST .

La acción realizada por el método POST podría no dar como resultado un recurso que pueda ser identificado por un URI. En este caso, 200 (OK) o 204 (Sin contenido) es el estado de respuesta apropiado, dependiendo de si la respuesta incluye o no una entidad que describa el resultado.

Si se creó un recurso en el servidor de origen, la respuesta DEBERÍA ser 201 (Creado) y contener una entidad que describa el estado de la solicitud y se refiera al nuevo recurso, y un encabezado de Ubicación (ver sección 14.30).

http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19

Es solo un valor clave delimitado por dos puntos.

ETag: "xyzzy"

Puede ser cualquier tipo de datos de texto: generalmente incluyo una cadena JSON con el identificador del elemento creado. La facilidad de las pruebas solo hace que valga la pena incluirlo.

ETag: "{ id: 1234, uri: 'http://domain.com/comments/1234', type: 'comment' }"

En este ejemplo, el identificador, la uri y el tipo del elemento creado son las "características y ubicación del recurso".

La salida depende realmente del tipo de contenido que se solicita. Sin embargo, como mínimo, debe colocar el recurso que se creó en Ubicación. Al igual que el patrón Post-Redirect-Get.

En mi caso, lo dejo en blanco hasta que se solicite lo contrario. Dado que ese es el comportamiento de JAX-RS cuando se utiliza Response.created ().

Sin embargo, solo tenga en cuenta que los navegadores y marcos como Angular no siguen los 201 automáticamente. He notado el comportamiento en http://www.trajano.net/2013/05/201-created-with-angular-resource/

Otra respuesta que tendría para esto sería adoptar un enfoque pragmático y mantener su contrato REST API simple. En mi caso, había refactorizado mi API REST para hacer que las cosas sean más comprobables sin recurrir a JavaScript o XHR, solo simples formularios y enlaces HTML.

Entonces, para ser más específico en su pregunta anterior, simplemente usaría el código de retorno 200y hacer que el mensaje devuelto contenga un mensaje JSON que su aplicación pueda entender. Dependiendo de sus necesidades, puede requerir la identificación del objeto que se acaba de crear para que la aplicación web pueda obtener los datos en otra llamada.

Una nota, en mi contrato API refactorizado, las respuestas POST no deben contener ningún dato almacenable en caché ya que los POST no son realmente almacenables en caché, así que limítelo a ID que se pueden solicitar y almacenar en caché utilizando una solicitud GET.