http - example - REST API PARCHE o PUT
rest post example (5)
La R en REST significa recurso
(Lo que no es cierto, porque significa Representacional, pero es un buen truco para recordar la importancia de los Recursos en REST).
Acerca de PUT /groups/api/v1/groups/{group id}/status/activate : no está actualizando un "activar". Un "activar" no es una cosa, es un verbo. Los verbos nunca son buenos recursos. Una regla de oro: si la acción, un verbo, está en la URL, probablemente no sea REST .
¿Qué estás haciendo en su lugar? Ya sea que esté "agregando", "eliminando" o "actualizando" una activación en un Grupo, o si lo prefiere: manipular un recurso de "estado" en un Grupo. Personalmente, usaría "activaciones" porque son menos ambiguas que el concepto "estado": crear un estado es ambiguo, crear una activación no.
-
POST /groups/{group id}/activationCrea (o solicita la creación de) una activación. -
PATCH /groups/{group id}/activationActualiza algunos detalles de una activación existente. Como un grupo solo tiene una activación, sabemos a qué recurso de activación nos referimos. -
PUT /groups/{group id}/activationInserta o reemplaza la activación anterior. Como un grupo solo tiene una activación, sabemos a qué recurso de activación nos referimos. -
DELETE /groups/{group id}/activationCancelará o eliminará la activación.
Este patrón es útil cuando la "activación" de un Grupo tiene efectos secundarios, como los pagos que se realizan, los correos electrónicos que se envían, etc. Solo POST y PATCH pueden tener tales efectos secundarios. Cuando, por ejemplo, una eliminación de una activación debe, por ejemplo, notificar a los usuarios por correo, ELIMINAR no es la opción correcta; en ese caso, es probable que desee crear un recurso de desactivación : POST /groups/{group_id}/deactivation .
Es una buena idea seguir estas pautas, ya que este contrato estándar lo deja muy claro para sus clientes, y todos los proxies y capas entre el cliente y usted, cuando es seguro volver a intentarlo y cuando no. Digamos que el cliente está en algún lugar con wifi inestable, y su usuario hace clic en "desactivado", lo que desencadena un DELETE : Si eso falla, el cliente simplemente puede reintentar, hasta que obtenga un 404, 200 o cualquier otra cosa que pueda manejar. Pero si desencadena una POST to deactivation , sabe que no debe volver a intentarlo: la POST implica esto.
Cualquier cliente ahora tiene un contrato que, cuando se cumpla, protegerá contra el envío de 42 correos electrónicos "su grupo ha sido desactivado", simplemente porque su biblioteca HTTP reintentó la llamada al backend.
Actualizando un solo atributo: usar PATCH
PATCH /groups/{group id}
En caso de que desee actualizar un atributo. Por ejemplo, el "estado" podría ser un atributo en los grupos que se puede configurar. Un atributo como "estado" es a menudo un buen candidato para limitar a una lista blanca de valores. Los ejemplos utilizan algún esquema JSON no definido:
PATCH /groups/{group id} { "attributes": { "status": "active" } }
response: 200 OK
PATCH /groups/{group id} { "attributes": { "status": "deleted" } }
response: 406 Not Acceptable
Reemplazando el recurso, sin efectos secundarios usa PUT.
PUT /groups/{group id}
En caso de que desee reemplazar un grupo entero. Esto no significa necesariamente que el servidor realmente cree un nuevo grupo y elimine al anterior, por ejemplo, los identificadores pueden seguir siendo los mismos. Pero para los clientes, esto es lo que puede significar PUT: el cliente debe asumir que obtiene un artículo completamente nuevo, basado en la respuesta del servidor.
El cliente debe, en caso de una solicitud PUT , enviar siempre el recurso completo, teniendo todos los datos necesarios para crear un nuevo elemento: por lo general, se requieren los mismos datos que una creación POST.
PUT /groups/{group id} { "attributes": { "status": "active" } }
response: 406 Not Acceptable
PUT /groups/{group id} { "attributes": { "name": .... etc. "status": "active" } }
response: 201 Created or 200 OK, depending on whether we made a new one.
Un requisito muy importante es que PUT es idempotente: si necesita efectos secundarios al actualizar un grupo (o cambiar una activación), debe usar PATCH . Por lo tanto, cuando la actualización dé como resultado el envío de un correo, no utilice PUT .
Quiero diseñar mi punto final de descanso con el método apropiado para el siguiente escenario.
Hay un grupo. Cada grupo tiene un estado. El grupo puede ser activado o desactivado por el administrador.
¿Debo diseñar mi punto final como
PUT /groups/api/v1/groups/{group id}/status/activate
O
PATCH /groups/api/v1/groups/{group id}
with request body like
{action:activate|deactivate}
Dado que desea diseñar una API utilizando el estilo arquitectónico REST, debe pensar en sus casos de uso para decidir qué conceptos son lo suficientemente importantes como para exponerlos como recursos. Si decide exponer el estado de un grupo como un sub-recurso, podría asignarle el siguiente URI e implementar el soporte para los métodos GET y PUT:
/groups/api/groups/{group id}/status
La desventaja de este enfoque sobre la modificación de PATCH es que no podrá realizar cambios en más de una propiedad de un grupo de forma atómica y transaccional. Si los cambios transaccionales son importantes, entonces use PATCH.
Si decide exponer el estado como un sub-recurso de un grupo, debe ser un enlace en la representación del grupo. Por ejemplo, si el agente obtiene el grupo 123 y acepta XML, el cuerpo de la respuesta podría contener:
<group id="123">
<status>Active</status>
<link rel="/linkrels/groups/status" uri="/groups/api/groups/123/status"/>
...
</group>
Se necesita un hipervínculo para cumplir con la hipermedia como el motor del estado del estado de la aplicación del estilo arquitectónico REST.
El método PATCH es la opción correcta aquí ya que está actualizando un recurso existente: la ID del grupo. PUT solo debe usarse si está reemplazando un recurso en su totalidad.
Más información sobre la modificación parcial de recursos está disponible en RFC 5789 . Específicamente, el método PUT se describe a continuación:
Varias aplicaciones que extienden el Protocolo de transferencia de hipertexto (HTTP) requieren una función para realizar una modificación parcial de los recursos. El método HTTP PUT existente solo permite una sustitución completa de un documento. Esta propuesta agrega un nuevo método HTTP, PATCH, para modificar un recurso HTTP existente.
En general, preferiría algo un poco más simple, como activate / deactivate sub-recurso (vinculado por un encabezado de Link con rel=service ).
POST /groups/api/v1/groups/{group id}/activate
o
POST /groups/api/v1/groups/{group id}/deactivate
Para el consumidor, esta interfaz es muy simple, y sigue los principios REST sin atascarse en conceptualizar las "activaciones" como recursos individuales.
Recomendaría usar PATCH, porque su ''grupo'' de recursos tiene muchas propiedades, pero en este caso, solo está actualizando el campo de activación (modificación parcial)
de acuerdo con el RFC5789 ( https://tools.ietf.org/html/rfc5789 )
El método HTTP PUT existente solo permite una sustitución completa de un documento. Esta propuesta agrega un nuevo método HTTP, PATCH, para modificar un recurso HTTP existente.
Además, en más detalles,
La diferencia entre las solicitudes PUT y PATCH se refleja en la forma en que el servidor procesa la entidad adjunta para modificar el recurso
Identificado por la Solicitud-URI. En una solicitud PUT, la entidad adjunta se considera una versión modificada del recurso almacenado en el
servidor de origen, y el cliente solicita que la versión almacenada
ser reemplazado Sin embargo, con PATCH, la entidad adjunta contiene un conjunto de instrucciones que describen cómo un recurso que actualmente reside en el
El servidor de origen debe ser modificado para producir una nueva versión. El método PATCH afecta el recurso identificado por el URI de solicitud, y
También PUEDE tener efectos secundarios sobre otros recursos; es decir, nuevos recursos
pueden ser creados, o los existentes modificados, por la aplicación de un
PARCHE.PATCH no es seguro ni idempotente como se define en [RFC2616], Sección 9.1.
Los clientes deben elegir cuándo usar PATCH en lugar de PUT. por
ejemplo, si el tamaño del documento de parche es más grande que el tamaño del
Los nuevos datos de recursos que se utilizarían en un PUT, entonces podrían hacer
Tiene sentido usar PUT en lugar de PATCH. Una comparación con POST es aún más difícil, porque POST se utiliza de maneras muy diversas y puede
abarcar operaciones similares a PUT y PATCH si el servidor lo elige. Si
la operación no modifica el recurso identificado por el URI de solicitud de una manera predecible, se debe considerar POST en lugar de PATCH
o PUT.
El código de respuesta para PATCH es
El código de respuesta 204 se usa porque la respuesta no lleva un cuerpo de mensaje (que tendría una respuesta con el código 200). Tenga en cuenta que también se pueden utilizar otros códigos de éxito.
también consulte thttp: //restcookbook.com/HTTP%20Methods/patch/
Advertencia: una API que implementa PATCH debe parchearse atómicamente. NO DEBE ser posible que los recursos estén medio parcheados cuando los solicite un GET.