Saltar al contenido principal

Principios Fundamentales de REST

🎯 Objetivo​

Regla​

1.1: Se debe comprender y aplicar rigurosamente los principios arquitectónicos fundamentales que definen el estilo REST, según lo establecido por Roy Fielding. 1.2: El diseño de servicios web debe basarse en estos principios para garantizar escalabilidad, flexibilidad y mantenibilidad, aprovechando las propiedades de la World Wide Web.

📖 Concepto y Definición​

Regla​

1.3: REST no debe ser interpretado como un protocolo o estándar rígido, sino como un conjunto de restricciones arquitectónicas. 1.4: La aplicación de estas restricciones a sistemas distribuidos de hipermedia debe conducir a propiedades deseables como rendimiento, escalabilidad, simplicidad, modificabilidad, visibilidad, portabilidad y fiabilidad.

Principios Clave Obligatorios​

1. Cliente-Servidor (Client-Server)​

Regla​

1.5: Se debe mantener una separación estricta de preocupaciones entre el cliente (iniciador de solicitudes, generalmente la interfaz de usuario) y el servidor (gestor de datos y lógica de negocio). 1.6: El cliente no debe gestionar el almacenamiento de datos, el cual debe permanecer interno al servidor. 1.7: El servidor no debe involucrarse con la interfaz de usuario o el estado del usuario, permitiendo la evolución independiente de ambas partes.

2. Sin Estado (Statelessness)​

Regla​

1.8: Cada solicitud del cliente al servidor debe contener toda la información necesaria para su procesamiento, sin que el servidor almacene contexto del cliente entre solicitudes referente al estado de la aplicación conversacional. 1.9: Si el estado de la aplicación es necesario para seguir una conversación o flujo de múltiples pasos, su mantenimiento es responsabilidad del cliente, quien debe enviarlo con cada solicitud pertinente. 1.10: Este principio debe ser respetado para mejorar la visibilidad, fiabilidad y escalabilidad. 1.10.1: La prohibición de estado en el servidor (Norma 1.8) se refiere específicamente al estado de la aplicación conversacional. El estado de autenticación y autorización, gestionado para fines de seguridad, debe ser validado por el servidor en cada solicitud. Esta validación debe basarse en credenciales (ej. tokens) enviadas por el cliente como parte de la solicitud auto-contenida, de acuerdo con lo estipulado en la Sección 7 (Seguridad).

Contexto/Justificación Adicional sobre Estado de Seguridad​

Si bien la Norma 1.8 prohíbe al servidor almacenar contexto del cliente entre solicitudes para el estado de la aplicación, es crucial entender su interacción con los mecanismos de seguridad (detallados en la Sección 7). En la práctica, el servidor valida el estado de autenticación y autorización en cada solicitud. Esto se logra comúnmente mediante tokens (ej. JWT) que el cliente envía. Cada solicitud sigue siendo "sin estado" desde la perspectiva de la lógica de la aplicación (no depende de interacciones previas para entender la solicitud actual del recurso), pero el servidor sí verifica la validez del token, los permisos asociados y la posible expiración de la sesión de seguridad que este representa. Esta gestión del estado de seguridad es intrínseca al procesamiento de la solicitud y no viola el principio REST fundamental siempre que la información necesaria para esta validación acompañe a cada petición. La ingeniería de software a menudo requiere adaptar principios teóricos a las necesidades funcionales y de seguridad del mundo real, buscando implementaciones limpias, consistentes y eficientes.

3. Cacheable (Cacheability)​

Regla​

1.11: Las respuestas del servidor deben indicar explícita o implícitamente si son cacheables. 1.12: Si una respuesta es cacheable, el cliente o un intermediario tiene el derecho de reutilizarla para solicitudes equivalentes posteriores durante el período especificado. 1.13: Se debe utilizar el cacheo para mejorar la eficiencia de la red, reducir la latencia y disminuir la carga del servidor.

4. Sistema de Capas (Layered System)​

Regla​

1.14: La arquitectura puede estar compuesta por múltiples capas de servidores (proxies, gateways, balanceadores de carga). 1.15: Un cliente debe interactuar con la capa de destino sin necesidad de conocer las capas intermedias. 1.16: Las capas intermedias pueden ofrecer funcionalidades adicionales, pero no deben romper la comunicación directa con la capa de destino aparente.

5. Interfaz Uniforme (Uniform Interface)​

Regla​

1.17: Se debe implementar una interfaz uniforme para simplificar y desacoplar la arquitectura, permitiendo la evolución independiente de sus partes. Esta consta de las siguientes sub-restricciones obligatorias:

  • 1.17.1 Identificación de Recursos: Los recursos individuales deben ser identificados unívocamente mediante URIs.
  • 1.17.2 Manipulación de Recursos a Través de Representaciones: La interacción del cliente con los recursos debe realizarse obteniendo o modificando representaciones de los mismos (ej. JSON, XML). La representación debe contener suficiente información para que el cliente pueda modificar o eliminar el recurso si posee los permisos.
  • 1.17.3 Mensajes Auto-Descriptivos: Cada mensaje (solicitud/respuesta) debe contener información suficiente para describir cómo procesarlo (ej. Content-Type para el parser, Cache-Control para el caché, método HTTP para la semántica de la operación).
  • 1.17.4 Hipermedia como el Motor del Estado de la Aplicación (HATEOAS): El cliente debe poder navegar la aplicación consumiendo hipervínculos presentes en las representaciones de los recursos. El servidor debe guiar las interacciones del cliente mediante estos enlaces, permitiendo la evolución de la API sin romper clientes.

6. Código Bajo Demanda (Code on Demand - Opcional)​

Contexto/Justificación​

Este principio es opcional en REST y menos común en APIs de datos.

Regla​

1.18: El servidor puede, opcionalmente, extender la funcionalidad del cliente transfiriendo lógica ejecutable (ej. scripts JavaScript). Su uso debe ser justificado y no es un requisito general para las APIs REST.

🤔 ¿Por qué es Importante? / Beneficios Clave (Contexto)​

Adherirse a los principios REST es crucial porque:

  • Escalabilidad: Las Reglas de statelessness y cacheabilidad deben ser aplicadas para permitir que los sistemas crezcan y manejen un gran volumen de solicitudes.
  • Simplicidad y Comprensibilidad: Una interfaz uniforme, como se norma, reduce la complejidad y facilita la comprensión.
  • Mantenibilidad y Evolución Independiente: La separación cliente-servidor y el sistema de capas, como se norma, permiten que diferentes partes evolucionen sin afectarse mutuamente. HATEOAS debe ser implementado para permitir modificar URIs y estructura sin romper clientes.
  • Fiabilidad: La naturaleza sin estado, como se norma, facilita la recuperación de fallos.
  • Rendimiento: El uso efectivo del caché, como se norma, reduce la latencia y carga.
  • Visibilidad: Las interacciones deben ser fáciles de monitorizar debido a mensajes auto-descriptivos y ausencia de estado en servidor.

✅ Buenas Prácticas y Recomendaciones Clave​

Regla​

1.19: Se debe priorizar la separación estricta Cliente-Servidor. 1.20: Se debe diseñar para la ausencia total de estado en el servidor respecto a la sesión del cliente. 1.21: Se deben definir y utilizar explícitamente directivas de caché HTTP (Cache-Control, ETag, Last-Modified). 1.22: La Interfaz Uniforme debe ser implementada rigurosamente:

  • Utilizar URIs para identificar inequívocamente cada recurso.
  • Emplear métodos HTTP estándar para las operaciones.
  • Utilizar tipos de medios (application/json por defecto) para definir el formato de las representaciones.
  • Se debe implementar HATEOAS para permitir a los clientes descubrir dinámicamente las capacidades de la API. 1.23: Las APIs deben ser diseñadas para funcionar correctamente detrás de intermediarios (proxies, balanceadores).

💡 Ejemplos Prácticos (Ilustrativos)​

Ejemplo 1: Statelessness (Norma 1.8, 1.9)​

Un cliente solicita información de un producto. Luego, solicita actualizar ese producto.

  • Solicitud 1 (GET):

    GET /products/123 HTTP/1.1
    Host: api.example.com
    Accept: application/json
    Authorization: Bearer <token_del_cliente_si_es_necesario>

    El servidor responde con los detalles del producto 123.

  • Solicitud 2 (PUT):

    PUT /products/123 HTTP/1.1
    Host: api.example.com
    Content-Type: application/json
    Accept: application/json
    Authorization: Bearer <token_del_cliente_si_es_necesario>

    {
      "name": "Producto Actualizado",
      "price": 19.99
    }

    El servidor actualiza el producto 123. Cada solicitud debe contener toda la información necesaria. El servidor no debe recordar nada de la primera solicitud para procesar la segunda.

Ejemplo 2: Interfaz Uniforme - Mensajes Auto-Descriptivos (Norma 1.17.3) y HATEOAS (Norma 1.17.4)​

Un cliente quiere crear un nuevo recurso "pedido".

POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json  // Norma: Indica que el cuerpo es JSON
Accept: application/json        // Norma: Indica que el cliente espera una respuesta en JSON
Authorization: Bearer <token_del_cliente>

{
  "productId": "prod_abc",
  "quantity": 2,
  "customerDetails": {
    "name": "Cliente Ejemplo",
    "address": "123 Calle Falsa"
  }
}

El servidor responde:

HTTP/1.1 201 Created
Content-Type: application/json  // Norma: La respuesta también es JSON
Location: /orders/789           // Norma: URI del nuevo recurso creado (sub-restricción de Interfaz Uniforme)
Cache-Control: no-cache         // Norma: Indica que esta respuesta no debe ser cacheada (ejemplo de uso de Cacheability)

{
  "data": {
    "orderId": "789",
    "status": "pending",
    "productId": "prod_abc",
    "quantity": 2,
    "totalAmount": 50.00
  },
  "_links": [
    {
      "rel": "self",
      "href": "https://api.example.com/v1/orders/789",
      "method": "GET"
    },
    {
      "rel": "customer",
      "href": "https://api.example.com/v1/customers/cust_xyz",
      "method": "GET"
    }
  ],
  "_meta": {
    "timestamp": "2023-10-27T12:00:00Z",
    "version": "1.0.0"
  }
}

El método POST, la URI /orders, los encabezados Content-Type y Accept, el código de estado 201 Created junto con el encabezado Location y los enlaces HATEOAS, deben contribuir a una interfaz uniforme y mensajes auto-descriptivos.

🛠️ Herramientas y Consideraciones Adicionales (Contexto)​

  • Disertación de Roy Fielding: Para una comprensión profunda, se recomienda la lectura del Capítulo 5 de la disertación de Roy T. Fielding.
  • Estos principios son guías. Desviarse significativamente puede llevar a perder los beneficios que REST ofrece. La Interfaz Uniforme es el principio más definitorio.