Restricciones de la arquitectura de la API REST: una guía de diseño

Las seis restricciones son: separación cliente-servidor, interacciones sin estado, capacidad de almacenamiento en caché, una interfaz uniforme, un sistema en capas y código bajo demanda opcional. Las cinco primeras definen características obligatorias; el comportamiento del ejecutable descargado es opcional. Roy Fielding desarrolla este conjunto en el capítulo 5 de su tesis doctoral.

Utiliza esta tabla para convertir los nombres en pruebas que puedas solicitar durante una revisión. Los ejemplos son preguntas de diseño, no un conjunto de pruebas de conformidad ni una promesa de que un solo encabezado haga que todo un sistema sea RESTful.

Las restricciones de la arquitectura de la API REST describen un sistema de interacciones. Una captura de pantalla de una sola respuesta no puede reflejar todas ellas. Recopila un breve rastro que contenga una lectura, una transición, un error y una solicitud repetida; a continuación, examina las suposiciones que conectan esos eventos.

Separa también la arquitectura de la selección tecnológica. HTTP es un entorno natural para las interfaces orientadas a recursos, pero un estilo arquitectónico no es una especificación de formato de conexión. Si tu equipo sigue comparando familias de diseño, la guía «API REST frente a API SOAP» explica por qué un estilo arquitectónico y un protocolo de mensajería requieren criterios de evaluación diferentes.

Imagina que un servicio de catálogo publica descripciones de productos y la disponibilidad de existencias. Un navegador elige el diseño visual, mientras que un recopilador elige un formato de almacenamiento. Ninguno de los consumidores necesita saber si el servicio lee una sola base de datos o combina varios sistemas. Esa separación es el punto de partida útil para el diseño cliente-servidor.

No lo interpretes como un requisito para crear un nuevo microservicio por cada recurso. Una sola aplicación puede exponer un límite claro. Por el contrario, muchos microservicios pueden exponer una interfaz profundamente acoplada si los llamantes deben conocer los nombres internos de las bases de datos, el orden de implementación o las etapas del flujo de trabajo no documentadas.

La siguiente consideración se refiere al estado de la conversación. Supongamos que un servicio requiere que un cliente seleccione primero un almacén y, a continuación, lee una solicitud de producto sin especificar de acuerdo con esa selección memorizada. Un trabajador sustituto no puede comprender la solicitud con solo mirarla. En un diseño sin estado, la solicitud identifica el almacén pertinente o, de otro modo, contiene información suficiente para interpretar la operación solicitada.

Esto no significa que el servicio olvide los productos, los pedidos o los permisos tras cada respuesta. Los datos empresariales persistentes constituyen el estado de los recursos. El problema radica en el contexto oculto de la conversación con el cliente necesario para comprender una solicitud posterior. Las restricciones de la arquitectura de la API REST resultan más fáciles de aplicar cuando se nombran explícitamente esos dos tipos de estado en el documento de diseño.

La autenticación requiere la misma atención. Un token de portador no es prueba de que todas las interacciones sean sin estado, y una consulta a la base de datos durante la autorización no es automáticamente prueba de lo contrario. Comprueba si la solicitud puede entenderse sin reconstruir las interacciones previas del cliente. A continuación, examina la autorización por separado: el servicio debe decidir si este solicitante puede acceder a este almacén y producto concretos.

En el caso de los recopiladores, documenta qué entradas de la solicitud pertenecen a una cuenta, una ubicación o una ejecución de recopilación. Mantén esas entradas asociadas a los elementos de trabajo al trasladarlos entre trabajadores. Si la integración también se basa en sesiones del navegador, comprende cómo las cookies HTTP conservan el contexto de la sesión antes de dar por sentado que copiar una URL reproduce la respuesta.

Supongamos que la descripción del producto cambia con poca frecuencia, mientras que la disponibilidad varía a lo largo del día. Asignar a ambas respuestas el mismo periodo prolongado de reutilización resulta conveniente para la infraestructura, pero puede ser erróneo para el consumidor. El diseño de la caché debe partir de la antigüedad aceptable de la información, no del deseo de reducir el volumen de solicitudes.

Para las API HTTP, el RFC 9111 define la reutilización de la caché y las directivas. Una respuesta puede prohibir el almacenamiento, exigir una validación antes de la reutilización o permitirla bajo condiciones específicas. no-cache no significa lo mismo que no-store: lo primero permite el almacenamiento, pero exige una validación satisfactoria antes de la reutilización; lo segundo indica a las cachés que no almacenen la respuesta.

Una etiqueta de entidad proporciona al consumidor un validador para una representación seleccionada. El recopilador puede enviar posteriormente If-None-Match; cuando se cumplen las condiciones aplicables para una solicitud GET, una 304 Not Modified respuesta le permite reutilizar la representación guardada. Esa respuesta no contiene ningún nuevo cuerpo de representación que analizar. Tratarla como un catálogo vacío corrompería una ejecución de recopilación que, por lo demás, funcionaría correctamente.

Las restricciones de la arquitectura de la API REST exigen un comportamiento de reutilización definido, no un almacenamiento en caché universal. Un informe específico de una cuenta puede requerir un tratamiento restrictivo, mientras que una descripción pública de una categoría puede tolerar un periodo de vigencia más largo. Una revisión del diseño debería identificar ambos casos en lugar de exigir un acierto en la caché para cada punto final.

Mantén las variantes diferenciadas. Si el idioma, las credenciales, la ubicación u otra entrada afecta a la respuesta, determina cómo esa entrada influye en la selección y la política de la caché. No des por sentado que una clave de caché basada únicamente en la URL es suficiente para datos personalizados. Las cachés compartidas también tienen restricciones específicas en torno a las solicitudes autenticadas, por lo que debes verificar el comportamiento implementado en lugar de confiar en la presencia de una única directiva.

En el almacenamiento de tu colección, conserva la hora de recuperación por separado de la hora de modificación proporcionada por la fuente. Responden a preguntas diferentes: cuándo observaste la representación y cuándo el editor indica que ha cambiado. Se trata de una recomendación de implementación para facilitar la auditabilidad, no de una séptima restricción REST.

La interfaz uniforme es la parte de las restricciones de la arquitectura de las API REST que resulta más fácil pasar por alto. En ella se incluyen cuatro requisitos: identificar los recursos, manipularlos a través de representaciones, hacer que los mensajes sean autodescriptivos y utilizar hipermedia para gestionar el estado de la aplicación. Evalúa cada uno de ellos en lugar de considerar que «utiliza GET y POST» es suficiente para la revisión completa.

Un identificador de producto hace referencia al recurso conceptual del producto; su documento JSON es una representación de ese recurso en un momento concreto. Una página generada, una imagen o un documento XML también pueden ser representaciones. Diseñar teniendo en cuenta esta distinción te ayuda a evitar exponer la estructura de una fila de la base de datos como si fuera el contrato público permanente.

Para el catálogo hipotético, especifica qué identificador permanece estable cuando cambia el nombre de un producto. Decide si las variantes tienen identidades independientes y si los productos descatalogados siguen siendo accesibles. Esas son decisiones propias del dominio. La prueba práctica consiste en comprobar si los clientes pueden referirse al elemento deseado sin tener que adivinar cómo lo almacena el servidor.

La manipulación a través de representaciones significa que el cliente opera a través de la interfaz publicada en lugar de modificar directamente las estructuras privadas del servidor. Una representación enviada sigue requiriendo la validación del servidor. Un precio, un identificador de propietario o un campo de permiso proporcionado por el cliente no se convierte en definitivo por el mero hecho de que la solicitud utilice un tipo de medio adecuado.

La autodescripción requiere algo más que nombres de campos legibles. La semántica de los métodos, el estado de la respuesta, el tipo de medio y los metadatos relevantes indican a los destinatarios cómo gestionar el mensaje. El mismo texto JSON puede significar cosas diferentes cuando se devuelve como una representación correcta o cuando se incluye en una respuesta de error.

Al utilizar HTTP, aplica su semántica de métodos real. GET es un método de recuperación seguro; PUT y DELETE son idempotentes en cuanto al efecto previsto que se les ha definido. La idempotencia no implica que cada repetición deba devolver un estado idéntico ni que se prohíba el registro. Estas distinciones se derivan de la semántica HTTP (RFC 9110) y son importantes cuando una integración considera reintentar una operación interrumpida.

Un colector debe comprobar el estado y el tipo de medio antes de analizar los registros esperados. Una conexión de red correcta seguida de un error de la pasarela HTML no constituye un catálogo JSON válido. Del mismo modo, un objeto JSON sintácticamente válido con un esquema de error no es una página que contenga cero productos.

La hipermedia como motor del estado de la aplicación, a menudo abreviada como HATEOAS, significa que los clientes seleccionan las transiciones disponibles a partir de los controles proporcionados por la interacción. Una representación de catálogo puede exponer un enlace a la página siguiente cuya relación tenga un significado definido. El colector sigue ese control en lugar de calcular cada URL futura a partir de una suposición privada sobre los desplazamientos.

La aclaración de Fielding sobre las API basadas en hipertexto convierte esto en un requisito definitorio, no en un adorno opcional. Los clientes siguen necesitando comprender el tipo de medio y la semántica de las relaciones. La hipermedia no hace que todos los flujos de trabajo empresariales desconocidos resulten comprensibles sin un contrato.

Para una revisión práctica, cambia la URL hipotética de la página siguiente de un desplazamiento a un cursor opaco. Un cliente que siga el control proporcionado no se verá afectado. Un cliente que lo descarte y incremente un número queda acoplado a una regla de construcción. El RFC 8288 define los enlaces web y los tipos de relación, proporcionando un vocabulario para enlaces cuyo significado es más preciso que un campo de URL arbitrario.

Por lo tanto, las restricciones de la arquitectura de la API REST plantean una pregunta más profunda que la mera existencia de enlaces: ¿guían realmente al cliente las transiciones admitidas? Añadir un self enlace a un procedimiento que, de otro modo, estaría codificado de forma rígida, no demuestra la existencia de una interfaz uniforme completa.

Un recopilador puede llegar a una pasarela que redirija a una caché y, a continuación, a una aplicación. Debería utilizar la interfaz publicada sin depender de qué instancia de la aplicación reciba la solicitud. Internamente, el operador puede cambiar el enrutamiento o sustituir un servicio conservando ese límite.

Las capas son también lugares donde las suposiciones fallan. Un proxy puede eliminar un encabezado, una pasarela puede sustituir una página de error o una caché puede combinar respuestas que deberían permanecer separadas. Revisa el comportamiento de extremo a extremo, así como la configuración de cada componente. Las restricciones de la arquitectura de la API REST no garantizan que un intermediario esté configurado correctamente.

Utiliza una pequeña matriz de rastreo para el catálogo hipotético: respuesta directa de la aplicación, respuesta de la pasarela, revalidación de la caché y tiempo de espera de los componentes anteriores. Compara el estado observable, los metadatos de representación y el contrato de error. Mantén un identificador de correlación que ayude a los operadores a rastrear los fallos, pero evita exigir a los clientes que comprendan los nombres de host internos o la topología de implementación.

El «código bajo demanda» aborda una cuestión diferente: un servidor puede ampliar el comportamiento de un cliente proporcionándole código ejecutable. Un navegador que carga un script ilustra este mecanismo. Su estado opcional es relevante porque muchos consumidores de API aceptan intencionadamente solo datos. Un servidor no necesita enviar JavaScript a un recopilador sin interfaz gráfica para cumplir las restricciones obligatorias.

Para las tareas de recopilación, haz explícito el límite de ejecución. Si una página necesita la ejecución del navegador para revelar datos, eso es un requisito operativo del objetivo. No es una prueba de que todos los clientes REST deban ejecutar respuestas arbitrarias. Del mismo modo, recibir HTML no implica que se esté utilizando el «código bajo demanda»; el contenido HTML y el comportamiento ejecutable son cuestiones distintas.

Considera la ejecución descargada como una capacidad independiente con sus propios controles. Mantén las credenciales de la API fuera de contextos de ejecución de páginas no relacionados y decide a qué hosts y destinos de navegación puede acceder un recopilador basado en navegador. Se trata de precauciones prácticas de implementación en torno al ejemplo, no de nuevas incorporaciones a la definición arquitectónica.

Empieza por un recorrido real del usuario en lugar de por el inventario de puntos finales. Para el ejemplo del catálogo, recupera una categoría, sigue una transición entre páginas, vuelve a visitar un producto sin cambios, encuentra un recurso no disponible y reanuda la ejecución tras el reinicio de un proceso de trabajo. Captura las solicitudes y respuestas depuradas para cada paso.

Para cada observación, distingue entre una propiedad demostrada y una suposición. Que el reinicio de un trabajador se realice con éxito una vez sugiere la portabilidad del contexto, pero no prueba que no haya una dependencia de sesión oculta en otro lugar. Un control de «página siguiente» demuestra una transición anunciada, pero no establece que toda la aplicación esté impulsada por hipermedia.

Las restricciones de la arquitectura de la API REST funcionan mejor como vocabulario de revisión. Anota «requiere una selección previa no documentada del almacén» en lugar de «REST incorrecta». Anota «el cliente construye URL de paginación a pesar de que se ha proporcionado una relación» en lugar de «no es moderna». Los hallazgos concretos apuntan a cambios que un desarrollador puede implementar y que un revisor puede verificar.

A continuación, prioriza los fallos según sus consecuencias. Una autorización incorrecta o el almacenamiento en caché entre cuentas requieren atención antes que una preferencia de nomenclatura. Un reintento que duplica el trabajo merece una estrategia de recuperación documentada. La ausencia de una capacidad opcional de código bajo demanda no necesita corrección simplemente para obtener la etiqueta REST.

En el caso de un servicio externo, es posible que no tengas la capacidad de modificar la interfaz. Adapta el colector al contrato documentado, conserva el contexto necesario y describe la limitación con sinceridad. Utilizar una API HTTP útil que no cumpla con los criterios estrictos de REST puede seguir siendo una buena elección de ingeniería. El error es dar por sentadas propiedades que la interfaz nunca prometió.

• Revisa las restricciones de la arquitectura de la API REST en función de los rastros de las solicitudes y las dependencias de los clientes, no de la presencia de JSON o de nombres de puntos finales atractivos.
• Separa los datos de recursos persistentes del estado oculto de la conversación y comprueba si el trabajo puede pasar de un consumidor a otro sin necesidad de reconstruir interacciones previas.
• Trata la actualidad, la validación, las variantes de representación y la gestión de errores como partes del contrato de datos antes de habilitar el almacenamiento en caché agresivo o los reintentos.
• Inspecciona los cuatro requisitos de la interfaz uniforme, incluidas las transiciones significativas; una lista de métodos HTTP solo cubre una parte del diseño.
• Registra las limitaciones concretas de la integración y sus consecuencias, de modo que las correcciones aborden la fiabilidad y la independencia, y no solo la terminología.

No. Las restricciones no prescriben una ubicación universal para el número de versión. Una política de versionado es una decisión del contrato que debe explicar cómo los clientes detectan los cambios y cómo se mantiene la compatibilidad. Antes de adoptar cualquier convención de nomenclatura, identifica qué cambios afectarían realmente a los usuarios existentes y cómo los comunicarás o los implementarás.

No. Un servicio puede utilizar transacciones de base de datos internamente al tiempo que expone una interfaz basada en REST. El cliente debe basarse en el comportamiento publicado, más que en la implementación de la base de datos. Decide qué consistencia promete la operación, qué significa una respuesta completada y cómo puede un solicitante investigar un resultado incierto tras un fallo de conexión.

No. No establecen cuotas de solicitud, límites de concurrencia ni un intervalo de espera universal. Esos aspectos pertenecen al contrato operativo del servicio. Los usuarios deben consultar los límites documentados por el proveedor, mantener la concurrencia dentro de unos límites y conservar suficiente información de diagnóstico para distinguir la limitación de tráfico de los errores de validación o de una infraestructura no disponible.

La revisión REST más productiva concluye con conclusiones observables. Debes saber qué contexto conlleva una solicitud, cuándo se puede reutilizar una respuesta, cómo la interpreta el cliente y de dónde proviene la siguiente acción admitida. También debes saber qué supuestos quedan sin comprobar detrás de las pasarelas o tras una interacción fallida.

Utiliza esos hallazgos para mejorar la siguiente integración. Incorpora una entrada que falte en el contrato explícito, corrige un límite de caché o enseña al cliente a seguir una transición proporcionada. Mantén visible la distinción entre requisitos arquitectónicos y recomendaciones operativas para que el equipo pueda tomar decisiones deliberadas.

Si tu canal de datos también necesita información disponible únicamente a través de páginas web, evalúa la API Scraper de WebScrapingAPI como una fuente de recopilación independiente. Aplica la misma disciplina a ese límite: valida la respuesta, conserva el contexto de la recopilación y documenta qué pueden suponer los consumidores posteriores sobre los datos devueltos.