La R en REST significa recurso
(Lo cual 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
: estás no actualizando una "activar". Un "activar" no es una cosa, es un verbo. Los verbos nunca son buenos recursos. Una regla general: si la acción, un verbo, está en la URL, probablemente no sea RESTful .
¿Qué haces en su lugar? O bien está "agregando", "eliminando" o "actualizando" una activación en un Grupo, o si lo prefiere: manipulando 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 lo es.
POST /groups/{group id}/activation
Crea (o solicita la creación de) una activación.
PATCH /groups/{group id}/activation
Actualiza algunos detalles de una activación existente. Como un grupo tiene solo una activación, sabemos a qué recurso de activación nos referimos.
PUT /groups/{group id}/activation
Inserta o reemplaza la activación anterior. Como un grupo tiene solo una activación, sabemos a qué recurso de activación nos referimos.
DELETE /groups/{group id}/activation
Cancelará o eliminará la activación.
Este patrón es útil cuando la "activación" de un Grupo tiene efectos secundarios, como los pagos realizados, los correos enviados, etc. Solo POST y PATCH pueden tener tales efectos secundarios. Cuando, por ejemplo, una eliminación de una activación necesita, 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, porque este contrato estándar lo deja muy claro para sus clientes, y todos los poderes y capas entre el cliente y usted saben cuándo es seguro volver a intentarlo y cuándo no. Digamos que el cliente está en algún lugar con wifi débil, y su usuario hace clic en "desactivar", lo que desencadena un DELETE
: Si eso falla, el cliente puede simplemente volver a intentarlo, hasta que obtenga un 404, 200 o cualquier otra cosa que pueda manejar. Pero si activa un POST to deactivation
, sabe que no debe volver a intentarlo: la POST implica esto.
Cualquier cliente ahora tiene un contrato que, cuando se sigue, protegerá contra el envío de 42 correos electrónicos "su grupo ha sido desactivado", simplemente porque su biblioteca HTTP seguía reintentando la llamada al backend.
Actualización de un solo atributo: use 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 pueden configurar. Un atributo como "estado" suele ser un buen candidato para limitarse a una lista blanca de valores. Los ejemplos usan algunos esquemas JSON indefinidos:
PATCH /groups/{group id} { "attributes": { "status": "active" } }
response: 200 OK
PATCH /groups/{group id} { "attributes": { "status": "deleted" } }
response: 406 Not Acceptable
Reemplazar el recurso, sin efectos secundarios, utiliza PUT.
PUT /groups/{group id}
En caso de que desee reemplazar un grupo completo. Esto no significa necesariamente que el servidor realmente cree un nuevo grupo y descarte el anterior, por ejemplo, los identificadores pueden seguir siendo los mismos. Pero para los clientes, esto es lo que PUT puede significar: el cliente debe asumir que obtiene un elemento completamente nuevo, basado en la respuesta del servidor.
El cliente, en caso de una PUT
solicitud, siempre debe enviar todo el recurso, con todos los datos necesarios para crear un nuevo elemento: por lo general, los mismos datos que requeriría 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
sea idempotente: si necesita efectos secundarios al actualizar un Grupo (o cambiar una activación), debe usarlo PATCH
. Entonces, cuando la actualización resulte, por ejemplo, en el envío de un correo, no lo use PUT
.