Cuando se construye un backend con una teoría y fundamento detrás las cosas cambian radicalmente y a la hora de exponer cierta información de negocio, los desarrollos pueden escalar exponencialmente bien. Para esto nació REST para diseñar un mejor manejo de la información.

REST no es algo nuevo, es algo más popular por así decirlo, dado que casi todo el mundo utiliza este diseño de arquitectura para exponer su información y conectar aplicaciones.

REST no es un protocolo, es más bien una interfaz que usa el protocolo HTTP para manejar recursos, comúnmente usando un formato JSON o XML.

La arquitectura de REST cuenta con las siguientes características:

Es sin estado

Para entender que es sin estado, hay que entender que significa el estado.

Cuando entras a un condominio que nunca has entrado, probablemente te pregunten a ¿Dónde vas? o ¿Qué vas a hacer?, probablemente te piden una identificación, o quizás no te dejen entrar y tengas que hablarle a alguien para que vaya por ti. Ahora te toca hacer eso todos los días durante un largo tiempo, lo mejor será que las personas de seguridad te conozcan y sepan quién eres para no demorarte las próximas veces.

En una aplicación real, el tener un estado significa que una aplicación te permita manejar la información, guardando quien eres en algún lugar.

REST es sin estado, es decir carece de almacenar tu identidad en cada solicitud que se realiza, esto desacopla mucho las aplicaciones, es decir el cliente no necesita los detalles del servidor, ni el servidor los detalles del cliente. Esto hace que cada petición de información sea independiente, pero no significa que no se necesite saber quien hace la petición, para algo se definieron cosas como JWT.

La manipulación de objetos mediante URL

Cuando navegamos en internet, cada página, sección, archivos, etc. que solicitamos se le conoce como recurso y es parte de la estructura de una URL:

{protocolo}://{dominio o hostname}[:puerto en caso de no ser 80]/{ruta del recurso}?{queries}

por ejemplo:

http://miapp.com/friends?show=family

En este caso el recurso solicitado es:

/friends

En REST toma importancia una gestión correcta de las rutas para acceder a los recursos y se rige por ciertas reglas:

  1. Los nombres deben ser únicos para acceder al mismo recurso o variantes del mismo:
/users
/usuarios

Si existieran estos nombres de recursos para obtener la misma información sería incorrecto. Lo correcto sería solo utilizar solo uno.

  1. Los nombres de los recursos no deben implicar acciones obvias, aunque sean descriptivas, por ejemplo no se debe hacer:
/obtener/usuarios/todos
/editar/usuario/inactivos
/getAllUsers
  1. Nombrar los recursos de una URL debe seguir una jerarquía lógica y entendible y si se desea filtrar información y se tiene disponible está opción, se debe usar las queries en los parámetros de las URL.
/2/orders/101/type/

Jerárquicamente no tiene sentido una URL así, porque si se desea obtener las órdenes de un tipo específico debería ser algo similar a esto:

/orders/101?type=2

Algo polémico es nombrar los recursos en inglés o español, realmente en español no está mal, lo que está mal a mi parecer, es nombrar los recursos en multi idiomas y combinarlos.

La importancia de los métodos HTTP

HTTP define unas acciones específicas por medio de verbos para ser usados por los recursos:

GET: Se limita a consultar y leer información.
POST: Crear nuevos recursos.
PUT: Actualizar la información de algún recurso.
DELETE: Eliminar algún recurso especificado.
OPTIONS: Define una serie de opciones de comunicación para el recurso solicitado.
PATCH: Editar partes específicas de un recurso.

Por ejemplo tenemos un recurso /orders, los métodos definirán qué acción tomar:

GET /orders
POST /orders
PUT /orders/{id}
DELETE /orders/{id}

No es necesario tener:

GET /orders/get
POST /orders/create
PUT /orders/update/{id}
DELETE /orders/delete/{id}

Como lo expliqué anteriormente está mal y sería redundante.

los códigos de respuesta HTTP

Los códigos de respuesta son utilizados para indicar si una solicitud de un recurso fue exitosa o no.

  1. Código informativo (rango de 100 a 199),
  2. Código de respuesta exitoso (rango 200 a 299),
  3. Redirecciones (rango 300 a 399),
  4. Errores de la parte solicitante (rango 400 a 499),
  5. Errores de servidor (rango 500 a 599).

developer.mozilla.org

REST nos permite utilizar estos códigos para notificar correctamente lo que pasó al solicitar un recurso. Un mal diseño sería utilizar un código de estatus exitoso (200) y una respuesta contraria en el cuerpo. Por ejemplo:

POST /orders/{id} Status Code 200

body:
{
  success: false,
  code: 734,
  error: "server error"
}

En donde se recibe un estatus OK, pero en la respuesta indica lo contrario. Si se recibe un cuerpo o una estructura de parte del recurso, debe tener lógica con el estatus de la respuesta.

Conclusión

REST nos permite modelar y crear servicios para ser consumidos por aplicaciones que pueden ser usadas por cualquier dispositivo o cliente que use HTTP (Y que tenga permisos). Al diseñar una API con REST e implementarla, tendremos una API RESTful o API REST.