rest - para - Crear solicitud con POST, qué códigos de respuesta 200 o 201 y contenido
http/1.1 200 ok (7)
Supongamos que escribo un servicio REST cuya intención es agregar un nuevo elemento de datos a un sistema.
Planeo hacer POSTAR a
http://myhost/serviceX/someResources
Supongamos que funciona, ¿qué código de respuesta debería usar? ¿Y qué contenido podría devolver?
Estoy mirando las definitions 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: lo que significa CREADO. Significado * La solicitud se ha cumplido y dio como resultado la creación de un nuevo recurso. Los URI (s) devueltos en la entidad de la respuesta pueden hacer referencia al recurso recién creado, con el URI más específico para el recurso dado por un campo de encabezado de ubicación. La respuesta DEBERÍA incluir una entidad que contenga una lista de características del recurso y ubicación (es) a partir de la cual el usuario o agente del usuario puede elegir la más apropiada. El formato de entidad se especifica mediante el tipo de medio proporcionado en el campo de encabezado Content-Type. *
Este último suena más en línea con la especificación Http, pero no estoy del todo claro qué
La respuesta DEBERÍA incluir una entidad que contenga una lista de características de recursos y ubicación (es)
medio.
Recomendaciones? Interpretaciones?
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 identificarse mediante 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 ha creado 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 haga referencia al nuevo recurso, y un encabezado de Ubicación (ver sección 14.30).
Creo que la API REST atompub es un gran ejemplo de un servicio tranquilo. Vea el siguiente fragmento 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>
La Entrada creada y devuelta por la Colección podría no coincidir 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.
El resultado depende del tipo de contenido que se solicita. Sin embargo, como mínimo debe colocar el recurso que se creó en la 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 usa Response.created ().
Sin embargo, solo tenga en cuenta que los navegadores y frameworks como Angular no siguen los 201 automáticamente. He notado el comportamiento en http://www.trajano.net/2013/05/201-created-with-angular-resource/
En pocas palabras:
- 200 cuando un objeto es creado y devuelto
- 201 cuando se crea un objeto pero solo se devuelve su referencia (como una ID o un enlace)
La idea es que el cuerpo de respuesta te brinde una página que te enlace con la cosa:
201 Creado
El código de estado 201 (Creado) indica que la solicitud se ha cumplido y ha resultado en la creación de uno o más recursos nuevos. El recurso principal creado por la solicitud se identifica mediante un campo de encabezado Ubicación en la respuesta o, si no se recibe un campo Ubicación, por el URI de solicitud efectiva.
Esto significa que incluiría una Location en el encabezado de respuesta que proporciona la URL de donde puede encontrar lo recién creado:
HTTP/1.1 201 Created
Date: Sat, 02 Apr 2016 12:22:40 GMT
Location: http://.com/a/36373586/12597
Cuerpo de respuesta
A continuación, mencionan lo que debe incluir en el cuerpo de respuesta:
La carga útil de la respuesta 201 típicamente describe y vincula a los recursos creados.
Para los humanos que usan el navegador, les da algo que pueden mirar, y hacen clic, para acceder a su nuevo recurso creado:
HTTP/1.1 201 Created
Date: Sat, 02 Apr 2016 12:22:40 GMT
Location: http://.com/a/36373586/12597
Content-Type: text/html
Your answer has been saved!
Click <A href="/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://.com/a/36373586/12597
Content-Type: application/xml
<createdResources>
<questionID>1860645</questionID>
<answerID>36373586</answerID>
<primary>/a/36373586/12597</primary>
<additional>
<resource>http://.com/questions/1860645/create-request-with-post-which-response-codes-200-or-201-and-content/36373586#36373586</resource>
<resource>http://.com/a/1962757/12597</resource>
</additional>
</createdResource>
O, si lo prefiere:
HTTP/1.1 201 Created
Date: Sat, 02 Apr 2016 12:22:40 GMT
Location: http://.com/a/36373586/12597
Content-Type: application/json
{
"questionID": 1860645,
"answerID": 36373586,
"primary": "/a/36373586/12597",
"additional": [
"http://.com/questions/1860645/create-request-with-post-which-response-codes-200-or-201-and-content/36373586#36373586",
"http://.com/a/36373586/12597"
]
}
La respuesta depende completamente de ti; es arbitrariamente lo que te gustaría.
Caché amigable
Finalmente está la optimización de que puedo precachear el recurso creado (porque ya tengo el contenido, acabo de subirlo). El servidor puede devolver una fecha o ETag que puedo almacenar con el contenido que acabo de subir:
Vea la Sección 7.2 para una discusión sobre el significado y el propósito de los campos del 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://.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="/a/36373586/12597">here</A> to view it.
Y ETag s son valores puramente arbitrarios. Hacer que sean diferentes cuando cambia un recurso (y las memorias caché deben actualizarse) es lo único que importa. El ETag es generalmente un hash (por ejemplo, SHA2). Pero puede ser una rowversion base de datos o un número de revisión creciente. Cualquier cosa que cambiará cuando la cosa cambie.
Otra respuesta que tendría para esto sería adoptar un enfoque pragmático y mantener el contrato de la API REST simple. En mi caso, he refactorizado mi API REST para que las cosas sean más comprobables sin recurrir a JavaScript o XHR, solo formularios y enlaces HTML sencillos.
Para ser más específico en su pregunta anterior, solo usaría el código de retorno 200 y el mensaje devuelto contendría un mensaje JSON que su aplicación puede comprender. Dependiendo de sus necesidades, puede requerir el ID 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 reajustado, las respuestas POST no deben contener ningún dato almacenable en caché ya que los POST no son realmente cacheables, por lo tanto, limítelos a los ID que pueden solicitarse y almacenarse en caché utilizando una solicitud GET.
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.
ETag: "{ id: 1234, uri: ''http://domain.com/comments/1234'', type: ''comment'' }"
En este ejemplo, el identificador, el uri y el tipo del elemento creado son las "características y ubicación del recurso".