Del endpoint único a la hipermedia: cómo evaluar, evolucionar y gobernar APIs HTTP sin confundir niveles de adopción con conformidad arquitectónica completa
Edición en profundidad - material de estudio y consulta profesional
Por João Ricardo Dutra••Material íntegro
Evolución de la interfaz según el modelo de madurez de Richardson
Descripción general: el único, las capacidades, la y los hipermedios forman una progresión acumulativa de capacidades observables.
Cada nivel agrega una habilidad de dibujo; el modelo no certifica la total conformidad con .
Presentación del capítulo
El modelo de madurez de Richardson, comúnmente abreviado como , organiza las interfaces de servicio en cuatro niveles: un punto de entrada orientado a mensajes, recursos identificables, uso semántico de y controles de . El modelo fue propuesto por Leonard Richardson y popularizado por Martin Fowler como una forma didáctica de descomponer algunos elementos centrales de un enfoque . Su valor radica en permitir a los equipos observar capacidades concretas de la interfaz sin depender únicamente de la etiqueta " ".
El modelo, sin embargo, no es un estándar de certificación y no reemplaza las restricciones arquitectónicas descritas por Roy Fielding. Una puede alcanzar el nivel 2 mediante el uso consistente de recursos, métodos y código y aun así mantener una sesión conversacional en el servidor, evitar el almacenamiento en caché, exponer detalles de implementación o crear un fuerte acoplamiento temporal. Asimismo, una interfaz puede adoptar enlaces sin que sus clientes naveguen realmente por las transiciones ofrecidas. Por tanto, nivel y calidad no son sinónimos automáticos.
En este capítulo, cada nivel se analizará en profundidad, con ejemplos de corporativas y bancarias ficticias. Se estudiarán los efectos sobre contratos, consumidores, , , , almacenamiento en caché, autorización, observabilidad y evolución. El objetivo no es defender que toda debe alcanzar el nivel 3, sino proporcionar criterios para elegir conscientemente hasta dónde avanzar y qué propiedades obtener.
El análisis también mostrará que la migración entre niveles no es sólo un intercambio de . Requiere identificar recursos, separar comandos de representaciones, asignar semántica correcta a métodos y respuestas, definir relaciones , planificar la compatibilidad y ajustar las políticas de . En entornos con muchos consumidores, la secuencia de evolución debe ser mensurable y reversible.
Cómo estudiar este capítulo Utilice la misma operación comercial al pasar por todos los niveles. Compare la forma de direccionamiento, la intención expresada por el método, los códigos devueltos, la posibilidad de almacenamiento en caché, las reglas de reintento y el conocimiento requerido por parte del cliente. La comparación revela mejor lo que añade cada nivel.
Objetivos de aprendizaje
Explicar el origen, propósito y límites del Modelo de Madurez de Richardson.
Diferenciar los niveles 0, 1, 2 y 3 por propiedades observables de la interfaz.
Reconocer patrones y mensajes imperativos concentrados en un .
Modele recursos estables sin confundir recursos, tablas, DTO y operaciones.
Aplique métodos, códigos, encabezados, caché y condiciones previas en el nivel 2.
Diseñar enlaces y acciones que representen transiciones permitidas.
Compare con restricciones arquitectónicas y con .
Evalúe las existentes sin convertir el análisis en una puntuación superficial.
Planifique la migración incremental, la gobernanza y la en .
Estructura del capítulo
11.1 Origen y finalidad del modelo
11.2 Qué mide y qué no mide
11.3 Descripción general de los cuatro niveles
11.4 Nivel 0: El pantano de POX
11.5 Estándares y riesgos operativos de nivel 0
11.6 Transición del nivel 0 al nivel 1
11.7 Nivel 1: Recursos
11.8 Identidad, granularidad y ciclo de vida
11.9 Limitaciones de nivel 1
11.10 Transición al nivel 2
11.11 Nivel 2: métodos y semántica
11.12 Estado, encabezados, caché y condiciones previas
11.13 , y errores
11.14 Nivel 2 en
11.15 Nivel 3: Controles de
11.16 Relaciones, vínculos y acciones
11.17 Tipos de contratos de medios e
11.18 Clientes orientados por transiciones
11.19 Beneficios, costos y dificultades del nivel 3
11,20 frente al de Fielding
11.21 , y gobernanza
11.22 Matriz de evaluación
11.23 Estrategia de migración
11.24 Observabilidad y
11.25 Estudios de casos y laboratorios
Resumen, lista de verificación, ejercicios, glosario y referencias.
11.1 Origen y finalidad del modelo
Leonard Richardson formuló el modelo como una forma de clasificar los estilos de servicios web mediante la adopción progresiva de funciones web. Martin Fowler lo popularizó en 2010 con la imagen de una escalera: en el nivel 0 hay un único punto de entrada orientado a mensajes; en el nivel 1 aparecen recursos; en el nivel 2 la interfaz utiliza métodos y respuestas ; en el nivel 3 las representaciones ofrecen controles . La simplicidad de esta descomposición ha hecho que sea útil en capacitación, revisiones de arquitectura y debates sobre modernización.
La palabra madurez puede dar lugar a una mala interpretación. Un nivel más alto no significa necesariamente que el producto, equipo o dominio sea "más maduro" en todos los aspectos. El modelo describe una dimensión específica de la interfaz. La seguridad, la disponibilidad, la gobernanza, la documentación, el rendimiento, la privacidad, la coherencia y la experiencia del desarrollador necesitan sus propias evaluaciones. Una de nivel 2 puede ser muy confiable y apropiada para el contexto; una de nivel 3 puede ser insegura o estar mal operada.
El modelo funciona mejor como lenguaje de diagnóstico. En lugar de simplemente preguntar “¿esta es ?”, el equipo puede preguntar: ¿hay recursos identificables? ¿Los métodos expresan intención? ¿La respuesta utiliza estados y encabezados coherentes? ¿El consumidor descubre transiciones a través de los ? Estas preguntas producen evidencia y decisiones en evolución.
Uso responsable del término madurez Utilice el nivel para describir las capacidades de la interfaz, no para clasificar personas o determinar la calidad total. Registre por separado atributos como seguridad, compatibilidad, , documentación, gobernanza y costo operativo.
11.2 Qué mide y qué no mide
observa principalmente tres movimientos: descomponer una operación genérica en recursos identificables, aprovechar la semántica estandarizada de y hacer que las transiciones sean visibles en la misma. Estos movimientos reducen parte del acoplamiento entre el consumidor y el servidor porque transfieren conocimiento a elementos web compartidos: , métodos, códigos, encabezados, enlaces y relaciones.
El modelo no verifica todas las restricciones . Cliente-servidor, , caché, sistema en capas y código bajo demanda no aparecen como pasos independientes. El nivel 2 aborda el almacenamiento en caché y la interfaz uniforme, y el nivel 3 aborda el como un controlador del estado de la aplicación, pero la evaluación completa de requiere un análisis arquitectónico más amplio. Por lo tanto, Fowler describe el nivel 3 como un paso hacia la “gloria del ”, no como una prueba automática de cumplimiento.
Tampoco existe una prueba universal para decidir el nivel cuando la mezcla estilos. Una plataforma puede tener puntos finales de consulta en el nivel 2, comandos heredados en el nivel 0 y un flujo específico con . En estos casos, clasificar toda la por un único número oculta información. El análisis deberá realizarse por superficie, o recorrido de negocio, registrando excepciones.
11.3 Descripción general de los cuatro niveles
Figura 1: organiza las capacidades de la interfaz en cuatro niveles acumulativos, pero no mide todos los atributos de una plataforma .
Tabla 1 - Capacidades, dependencias y riesgos asociados a cada nivel.
Nivel
Elemento agregado
Conocimiento básico del cliente
Riesgo característico
0
Mensajes sobre un punto final
Operaciones y formato propietario
Dispatcher central, poca semántica compartida
1
Recursos e identificadores
Qué recursos existen y cómo abordarlos
Recursos tratados únicamente como sobres de comando
2
Métodos HTTP, estado y encabezados
Semántica de protocolo y contrato de recursos.
Uso decorativo de verbos o códigos inconsistentes.
3
Controles de hipermedia
Relaciones y tipos de medios.
Enlaces sin semántica ni clientes que siguen codificando el flujo
11.4 Nivel 0: El pantano de POX
En el nivel 0, el servicio normalmente publica un único y utiliza el cuerpo del mensaje para indicar qué operación se debe realizar. POX significa "Plain Old ", una expresión histórica para mensajes sin aprovechar recursos web más ricos; En la práctica actual, la misma estructura puede aparecer con , Protobuf u otro formato. El aspecto decisivo no es el formato, sino la concentración de intenciones en una interfaz genérica.
Un servicio de pagos siempre podría recibir pagos /servicio y distinguir operaciones por un campo como operación. Verificar saldo, crear transferencia, cancelar cita y emitir estado de cuenta comparten la misma dirección y método. El servidor actúa como dispatcher: interpreta el comando y lo reenvía a la rutina correspondiente. Muchos servicios , sobre e integraciones heredadas se acercan a este nivel.
Figura 2 - En el nivel 0, el protocolo transporta un mensaje propietario y el cuerpo concentra la intención de la operación.
El nivel 0 no es sinónimo de mala implementación. En escenarios cerrados, colas de comandos, protocolos binarios, operaciones altamente especializadas o compatibilidad con sistemas heredados, puede ser una decisión válida. El problema surge cuando la organización espera propiedades de la Web -almacenamiento en caché, semántica uniforme, visibilidad a través de intermediarios y evolución desacoplada-sin exponer elementos que permitan obtenerlas.
11.5 Estándares y riesgos operativos de nivel 0
La principal consecuencia es que los componentes intermedios ven poca diferencia entre las operaciones. Una observa múltiples para la misma ruta y la distinción real está oculta en el cuerpo. Las reglas de autorización, cuotas, almacenamiento en caché, métricas y enrutamiento deben inspeccionar el contenido o confiar en campos propietarios. Esto aumenta los costos de las políticas, reduce el rendimiento y dificulta la correlación con herramientas que agregan métricas por método y ruta.
Los también se vuelven riesgosos. El método no indica si una operación es repetible y el mismo puede contener consultas, comandos idempotentes y comandos no idempotentes. Un tiempo de espera deja al cliente sin saber si el servidor realizó la acción. La solución a menudo requiere identificadores de correlación, claves de o estado de procesamiento, pero estos mecanismos deben definirse fuera de la semántica básica del protocolo.
Los errores suelen devolver 200 con un sobre que contiene Success=false o códigos internos. Esta práctica evita que los balanceadores de carga, las puertas de enlace, los y la observabilidad utilicen la clase de estado como señal. También crea ambigüedad entre fallas en el transporte, rechazo del y errores comerciales. El consumidor necesita interpretar el cuerpo antes de clasificar cualquier resultado.
Señal de nivel 0 Si la documentación comienza con una lista de operaciones aceptadas en un campo acción, comando, operación o nombre de servicio y casi todo usa en la misma ruta, la interfaz probablemente esté en el nivel 0, incluso cuando los mensajes son y el producto se llama .
Tabla 2 - Efectos típicos de una interfaz concentrada en el nivel 0.
Síntoma
Impacto en la puerta de entrada
Impacto en el consumidor
Un URI para todo
Las políticas dependen de la inspección corporal.
El SDK necesita conocer los códigos internos y del dispatcher
200 por acierto y error
Las métricas de estado se vuelven engañosas
El manejo de errores depende del sobre.
POST para leer y escribir
El caché y la seguridad no pueden inferir la intención
El reintento requiere una regla específica por operación
Contrato básico extenso
Los cambios afectan a una gran superficie.
El control de versiones y las pruebas se vuelven monolíticos
11.6 Transición del nivel 0 al nivel 1
La primera transición consiste en hacer explícitas las entidades o conceptos que tienen identidad y ciclo de vida. En lugar de enviar todos los mensajes a /servicio, la interfaz ahora aborda clientes, cuentas, transferencias, citas y extractos. Este cambio requiere comprender el ámbito: una transferencia no es sólo una función; se puede crear, validar, confirmar, rechazar, cancelar y consultar a lo largo del tiempo.
La migración debe comenzar con el inventario. Cada operación del dispatcher se clasifica como consulta, creación, cambio, comando, proceso o integración. A continuación, el equipo identifica qué objetos necesitan una dirección estable, cuáles están subordinados a otros y cuáles representan procesos. El objetivo no es convertir cada tabla en un , sino encontrar unidades de significado a las que los consumidores puedan hacer referencia.
La compatibilidad se puede preservar con una capa de adaptación. El heredado continúa aceptando mensajes y llama internamente a los nuevos servicios orientados a recursos. Los nuevos consumidores adoptan la nueva superficie, mientras que las métricas miden la reducción del uso del antiguo contrato. Esta estrategia evita una migración “big bang” y le permite validar el modelado antes de eliminar el dispatcher.
Pregunta de modelado ¿Qué es necesario identificar, consultar o referenciar una vez completada la operación? La respuesta suele revelar un . Una solicitud de transferencia, por ejemplo, sigue existiendo como entidad auditable incluso después de la respuesta inicial.
11.7 Nivel 1: Recursos
En el nivel 1, la interfaz publica múltiples recursos con sus propios identificadores. El consumidor ya no conoce sólo una genérica y comienza a interactuar con direcciones que representan partes del dominio. El sirve como identificador, no como una descripción completa de la implementación. /transferencias/abc puede seguir siendo válido incluso si el servicio cambia de banco, idioma o topología.
El modelo no requiere el nivel 1 para utilizar correctamente todos los métodos . La puede seguir enviando a /clientes/483/consultar, /transferencias/abc/cancelar o /cuentas/991/extracto. Ha habido avances en la identificación, pero la intención todavía está parcialmente codificada en los verbos de ruta o en el cuerpo. Esta característica explica por qué los recursos son necesarios pero insuficientes para una interfaz semánticamente rica.
Figura 3: Las capacidades distintivas hacen visibles la identidad y el alcance, aunque las operaciones aún pueden seguir siendo imperativas.
11.8 Identidad, granularidad y ciclo de vida
Un es una abstracción identificable, no necesariamente una línea bancaria. Puede representar una entidad duradera, una colección, una proyección, un documento, un proceso o el resultado de un cálculo. /limits-operacional/cliente-483 puede ser una vista calculada; /solicitudes-transferencia/abc puede representar un proceso; /extractos/cuenta-991/2026-07 puede representar un documento elaborado por un período.
La granularidad debe reflejar patrones de cohesión y acceso. Recursos excesivamente grandes obligan a los consumidores a transferir y actualizar datos irrelevantes. Los recursos muy fragmentados aumentan los viajes de ida y vuelta y la complejidad de la composición. En los sistemas corporativos, los límites también deben considerar la autorización, la propiedad, la coherencia transaccional y la capacidad de evolución independiente.
Los identificadores públicos no deberían exponer las claves internas innecesariamente. Un número secuencial puede facilitar la enumeración y revelar el volumen; una clave de tabla puede cambiar durante las migraciones. La puede utilizar identificadores opacos, alias comerciales o estables. Lo importante es definir la unicidad, alcance, permanencia y comportamiento cuando el es eliminado o reemplazado.
Tabla 3 - Preguntas para modelar recursos en el nivel 1.
decisión
pregunta técnica
Ejemplo
Identidad
¿Es necesario hacer referencia al recurso más adelante?
/transferencias/{id}
Alcance
¿La identidad es global o subordinada?
/cuentas/{cuenta}/programaciones/{id}
Granularidad
¿Qué datos cambian y se autorizan juntos?
preferencias de registro separadas
ciclo de vida
¿Qué estados y transiciones hay?
PENDIENTE -> CONFIRMADO -> RESUELTO
Permanencia
¿Sobrevive el identificador a las migraciones internas?
identificación pública opaca
11.9 Limitaciones de nivel 1
La separación de recursos mejora la observabilidad y la organización, pero no resuelve por sí sola la semántica de las operaciones. Puntos finales como /transferencias/abc/consultar y /transferencias/abc/eliminar aún ocultan propiedades conocidas por . El no puede inferir que la consulta es segura o que la eliminación debería producir una determinada clase de respuesta. El cliente depende de convenciones específicas de cada .
Otro riesgo es crear “recursos falsos” sólo para dar cabida a los verbos. Rutas como /crearTransferencia, /ejecutarPago u /obtenerClientes utilizan múltiples direcciones, pero continúan modelando funciones. Esta interfaz puede ser clara y funcional, pero el progreso hacia una interfaz uniforme es limitado. El análisis debe centrarse en el significado del identificador, no sólo en contar las .
En el nivel 1, las colecciones y relaciones también pueden ser inconsistentes. Un equipo puede utilizar /cliente/483/cuenta y otro /consultarContasPorCliente?id=483. Sin estándares de denominación, cardinalidad, paginación y errores, la expansión de recursos aumenta la superficie sin generar previsibilidad. La gobernanza sigue siendo necesaria.
11.10 Transición al nivel 2
La segunda transición consiste en asignar intenciones a la . Las consultas utilizan o ; la creación suele utilizar en la colección; la sustitución idempotente puede usar ; la eliminación utiliza ; Las actualizaciones parciales pueden usar cuando se definen su formato y semántica. El método deja de ser sólo un campo de transporte y pasa a comunicar propiedades a clientes e intermediarios.
Esta migración también requiere revisar las respuestas. La creación puede devolver 201 Created con Location; el procesamiento asincrónico puede utilizar 202 Accepted; la condición previa insatisfecha puede producir 412; el conflicto estatal puede producir 409; la validación puede utilizar . Encabezados como , -Control, Allow, -After y Vary pasan a formar parte del contrato.
No basta con reemplazar con verbos diferentes. El comportamiento debe respetar la seguridad, la y la semántica. Un que cancela una programación sigue siendo peligroso, incluso si la ruta parece orientada a recursos. Un que crea efectos adicionales en cada repetición no es idempotente. El nivel 2 se basa en el comportamiento observable, no en la decoración sintáctica.
Ejemplo de lectura con
GET /transferencias/abc HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "v7"
{ "id": "abc", "status": "PENDIENTE", "importe": 120.00 }
Criterios de transición Para cada operación, registre: de destino, método, propiedad de seguridad, , respuesta exitosa, errores, encabezados, capacidad de caché y política de reintento. La tabla destaca dónde cambiar el verbo requiere un cambio real de comportamiento.
11.11 Nivel 2: métodos y semántica
En el nivel 2, la interfaz utiliza el vocabulario para expresar intenciones. La semántica se comparte entre navegadores, bibliotecas, servidores , puertas de enlace y herramientas de observabilidad. es seguro y no debería solicitar un cambio de estado; y son idempotentes; es flexible y normalmente no idempotente; tiene la misma semántica que sin contenido de respuesta. depende del tipo de documento de parche utilizado.
El beneficio no es sólo estético. Una puede aplicar diferentes reglas de lectura y escritura, las cachés pueden reutilizar respuestas, los pueden clasificar los resultados por estado, los clientes pueden implementar de operaciones idempotentes de forma más segura y los equipos de SRE pueden agrupar métricas por método y ruta. La interfaz se vuelve más visible para los componentes que no conocen el dominio.
Figura 4: Los métodos y respuestas estandarizados permiten que los componentes genéricos comprendan las propiedades de interacción.
11.12 Estado, encabezados, caché y condiciones previas
Los códigos de estado clasifican el resultado de intentar procesar la solicitud. No reemplazan los detalles del dominio, pero proporcionan una primera capa interoperable. 2xx indica procesamiento exitoso; 3xx aconseja redirección o reutilización; 4xx indica que la solicitud no puede atenderse en las condiciones presentadas; 5xx apunta a una falla del servidor o intermediario. La elección debe reflejar quién produjo la respuesta y el estado observado.
Los encabezados amplían la semántica. Location identifica el creado o la ubicación relevante; representa una versión de la ; If-Match y If-None-Match expresan condiciones previas; -Control controla la reutilización; -After orienta el reintento; Allow informa los métodos compatibles; Vary describe qué campos de la solicitud influyen en la respuesta. Ignorar estos elementos reduce el nivel 2 a una tabla de verbos.
Las condiciones previas son especialmente importantes en las empresariales. Dos consumidores pueden leer la versión v7 de un e intentar actualizarlo. Sin control, la última escritura sobrescribe la anterior. Con e If-Match, el servidor realiza el cambio sólo si la versión aún coincide. Si el estado ha cambiado, devuelve 412 Precondition Failed, lo que permite al cliente recargar y reconciliar.
Tabla 4 - Elementos del protocolo que hacen que la interfaz sea más operable.
Elemento HTTP
Usar en el nivel 2
Fallo común
201 + Location
Confirmar creación e informar identificador.
Devuelve 200 sin referencia a un nuevo recurso.
202 + monitor
Proceso de aceptación aún no completado
Tratar la aceptación como el éxito final
ETag/Si coincide
Previene la pérdida de actualizaciones
Generar ETag sin validar condiciones previas
Control de caché
Define reutilización y revalidación.
Respuesta sensible al caché sin política explícita
Retry-After
Guía nuevo intento
Responder 429/503 sin ventana ni estrategia
11.13 , y errores
significa que repetir la misma solicitud produce el mismo efecto deseado en el servidor, aunque la de la respuesta puede variar. y se definen como idempotentes; no recibe esta garantía por defecto. En sistemas distribuidos, el tiempo de espera no prueba que la operación haya fallado. El cliente puede perder la respuesta después de que el servidor complete el comando, creando un riesgo de duplicación.
Para operaciones no idempotentes, una clave de puede asociar intentos equivalentes con un único resultado. El servidor necesita definir el alcance, la caducidad, la comparación de la carga útil, la persistencia y el comportamiento concurrente. El puede requerir el formato de encabezado y límite, pero la deduplicación empresarial generalmente pertenece al servicio que conoce la operación y su transacción.
Los errores deben combinar el estado y una estable. , actualmente definido por 9457, proporciona campos como tipo, título, estado, detalle e instancia, así como extensiones. El estado clasifica el resultado; el tipo identifica una categoría de problema; Las extensiones llevan datos estructurados. Los mensajes internos, los seguimientos de la pila y los datos confidenciales no deben exponerse.
Error estructurado en el nivel 2
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
{
"type": "https://api.ejemplo/problemas/estado-invalido",
"title": "Transición no permitida",
"status": 409,
"detail": "La transferencia ya fue liquidada.",
"instance": "/transferencias/abc"
}
El reintento no es solo la configuración del cliente. La estrategia depende del método, la , la fase de falla y la capacidad de deduplicación. Repetir automáticamente un financiero después del tiempo de espera sin una clave de puede duplicar los efectos.
11.14 Nivel 2 en
se benefician directamente de la semántica de nivel 2. Las políticas pueden separar la lectura y la escritura por método, aplicar cuotas por operación, bloquear métodos no publicados, validar el tipo de contenido y aceptar, propagar ID de correlación, producir 405 cuando el método no está permitido y normalizar errores de infraestructura. Las métricas por plantilla de ruta y estado se vuelven más representativas.
El , sin embargo, no transforma una al nivel 2 simplemente reescribiendo rutas o métodos. Si recibe e internamente llama a un comando que cambia de estado, se ha violado la propiedad de seguridad. Si convierte cada error de en 200, destruye la semántica. Si agrega sin asegurarse de que la versión represente el estado, crea una condición previa falsa. La responsabilidad debe ser compartida con el servicio.
En arquitecturas de múltiples saltos, debe registrar dónde se creó cada respuesta. Un 429 puede provenir del de cuota, un 503 del balanceador, un 409 del dominio y un 401 del proveedor de identidad. La estandarización ayuda al consumidor, pero los registros y los encabezados de correlación deben preservar la fuente para la .
Figura 5 - El refuerza la interfaz y aplica políticas transversales; la semántica del dominio todavía pertenece a la .
Tabla 5 - Uso del nivel 2 en políticas de gateway.
politica
Responsabilidad adecuada
Antipatrón
Autenticación
Validar credencial y contexto
Inventar autorización ligera sin datos de dominio
Enrutamiento
Asignar contrato a upstream
Enmascarar rutas incompatibles sin observabilidad
Limitación de velocidad
Proteger la capacidad y los planes
Utilice el mismo límite para lecturas ligeras y comandos costosos
Validación
Rechazar forma de contrato no válida
Acepte la carga útil y cambie el significado silenciosamente
Transformación de errores
Normalizar la infraestructura y el formato
Convierta todos los errores a 200 o 500
11.15 Nivel 3: Controles de
El nivel 3 agrega controles a las representaciones. Además de devolver datos, el servidor informa las relaciones y transiciones disponibles en el estado actual. Una transferencia pendiente puede ofrecer enlaces self, confirm y cancel; una transferencia liquidada solo puede ofrecer self y receipt. El cliente no necesita construir todas las ni mantener una tabla de estados completa para saber qué acciones están habilitadas.
Este enfoque está relacionado con el principio : como motor del estado de la aplicación. El “estado de la aplicación” se refiere al progreso del cliente a través de una secuencia de interacciones, guiadas por controles entrantes. El servidor continúa controlando el estado de los recursos, mientras la describe posibles rutas. La Web funciona de esta manera cuando un navegador recibe enlaces y formularios.
Figura 6: La de una transferencia pendiente expone solo las transiciones permitidas en ese momento.
Un enlace útil tiene un destino y una relación semántica. La relación consigo mismo indica la identificación canónica de la ; siguiente y anterior pueden navegar por las páginas; puntos de recogida a la recogida; El artículo relaciona colección y miembro. Las relaciones registradas en la permiten un significado compartido, mientras que las relaciones específicas pueden utilizar sus propios . El nombre del campo por sí solo no debería ser la única definición semántica.
Las acciones requieren más información que un href. El cliente puede necesitar método, tipo de contenido, campos, restricciones y documentación. Los diferentes formatos representan esta información de diferentes maneras. No existe un formato único obligatorio para ; el contrato debe definir el tipo de medios, las relaciones y cómo interpretar los controles.
Los controles deben reflejar la autorización y el estatus, pero su ausencia no reemplaza la aplicación de la ley. El servidor debe validar cada acción nuevamente. Un cliente puede fabricar una solicitud o reutilizar un enlace antiguo. La guía la experiencia y reduce los intentos no válidos; la autorización y la validación siguen siendo obligatorias.
Tabla 6 - Las relaciones deben tener un significado estable y documentado.
relación
Posible significado
Nota
yo
Identificador de representación actual
Ayuda para el almacenamiento en caché, la correlación y la actualización
colección
Colección a la que pertenece el artículo
Puede guiar la navegación y la creación.
siguiente/anterior
Paginación o secuencia
Prefiero enlaces completos a la reconstrucción del cursor.
confirmar
Transición de dominio específico
Definir relación por URI o contrato de medios
descrito por
Documento que describe el recurso.
No reemplaza los controles ejecutables.
11.17 Tipos de contratos de medios e
Los dependen de una convención que el cliente entiende. application/ , por sí solo, solo define la sintaxis ; no le dice que los _links contienen relaciones, que las acciones describen formularios o cómo se deben expandir las plantillas de . La puede adoptar un tipo de medio conocido, un perfil o un tipo específico de organización. Lo importante es que el significado sea explícito y versionable.
Los tipos de medios específicos pueden permitir la evolución independiente de las , pero también aumentar la gobernanza y las herramientas. Los , validadores, puertas de enlace y documentación necesitan conocer el formato. En organizaciones con muchos equipos, una especificación interna debe definir campos obligatorios, relaciones registradas, plantillas, acciones, errores, compatibilidad y reglas de seguridad.
Los , definidos por 8288, le permiten transportar enlaces en encabezados y representaciones. Las plantillas , definidas por 6570, permiten describir destinos parametrizados. Estos patrones pueden componer una solución, pero no proporcionan por sí solos un modelo completo de acciones. La elección debe considerar las capacidades reales de los consumidores.
no tiene de forma predeterminada. Un campo llamado enlaces son solo datos hasta que el contrato define relaciones, objetivos, cardinalidad, plantillas y comportamiento del cliente. La madurez está en la semántica compartida, no en el nombre del objeto.
11.18 Clientes orientados por transiciones
Un cliente impulsado por comienza con un pequeño conjunto de puntos conocidos y navega a través de relaciones. Busca rel=confirmar, en lugar de concatenar /confirmación; interpreta una acción disponible, en lugar de codificar que PENDIENTE siempre permite la confirmación. Esto reduce el acoplamiento a la topología y parte de las reglas de flujo.
La reducción no es absoluta. El cliente aún conoce las relaciones, los tipos de medios y la semántica de dominio. Cambiar el significado de confirmar es un cambio radical. Eliminar una relación puede cambiar la funcionalidad. La cambia el acoplamiento de y secuencias rígidas a vocabularios y posibilidades, que necesitan gobernanza.
Los clientes generados exclusivamente desde tienden a llamar a operaciones estáticas. Para explorar el nivel 3, el tiempo de ejecución necesita analizar representaciones y elegir transiciones. Es posible combinar los enfoques: describe operaciones y esquemas, mientras que las relaciones en las respuestas guían la disponibilidad y la navegación. Las pruebas deben verificar ambos.
Pseudocódigo de cliente basado en relaciones
transfer = GET(entrypoint).follow("transfer-by-id", id="abc")
if transfer.has_relation("confirm"):
result = transfer.follow("confirm", body={"otp": "..."})
else:
show_message("La confirmación no está disponible en el estado actual")
11.19 Beneficios, costos y dificultades del nivel 3
El principal beneficio es que permite al servidor comunicar transiciones válidas y cambiar ciertos destinos sin necesidad de que los clientes reconstruyan las . Esto puede mejorar la capacidad de descubrimiento, reducir las llamadas no válidas, facilitar transmisiones largas y hacer que el estado sea más explícito. En dominios con máquinas de estado relevantes (incorporación, pagos, pedidos, aprobaciones), los controles dinámicos pueden aportar un valor concreto.
El costo aparece en diseño, documentación, bibliotecas y pruebas. El equipo necesita definir vocabularios de relaciones, representar acciones, mantener tipos de medios y educar a los consumidores. Las herramientas empresariales están más maduras para y estáticos que para clientes genéricos. Si los consumidores ignoran los enlaces y continúan concatenando caminos, el costo se paga sin obtener el beneficio.
Un error común es devolver todos los enlaces posibles, independientemente del estado o la autorización. Esto convierte a los en un catálogo estático y puede exponer información innecesaria. Otra es utilizar relaciones indefinidas, como acción1 o ejecutar. También es inapropiado creer que los enlaces eliminan las versiones: los esquemas, las relaciones y la semántica continúan evolucionando.
Tabla 7 - La decisión de adoptar hipermedia depende del dominio y del ecosistema.
Situación
El nivel 3 tiende a ayudar
El nivel 3 puede no dar sus frutos
Flujo de negocios
Múltiples estados y transiciones dinámicas
CRUD simple y estable
Consumidores
Clientes capaces de interpretar las relaciones.
Integraciones por lotes estrictas y SDK generados
Topología
Los destinos y las acciones evolucionan con frecuencia.
Pocas operaciones y URL estables
Gobernanza
Vocabulario compartido y tipo de medios.
Cada equipo inventa su propio formato
Operación
Telemetría de relaciones y transiciones.
Los enlaces no se observan ni se prueban.
11,20 frente al de Fielding
El es una descomposición didáctica de algunos elementos; es un estilo arquitectónico compuesto de limitaciones. El nivel 1 se relaciona con la identificación de recursos. El nivel 2 es el que más se acerca a una interfaz uniforme y al uso de la . El nivel 3 enfatiza los controles . Sin embargo, el modelo no tiene pasos explícitos para cliente-servidor, , caché, sistema en capas y código bajo demanda.
Una puede estar en el nivel 3 y aún depender de la afinidad de sesión en una instancia, deshabilitar el almacenamiento en caché en todas las respuestas, exponer detalles de persistencia y requerir coordinación simultánea entre el cliente y el servidor con cada cambio. En esta situación, la interfaz utiliza , pero la arquitectura no logra varias propiedades esperadas.
Lo contrario también requiere matices. Una de nivel 2 puede aplicar cliente-servidor, , caché y capas de forma robusta, quedando lejos del uso completo del . Llamarlo “inmaduro” sin considerar el contexto puede ser menos útil que registrar exactamente qué restricciones y propiedades están presentes.
Tabla 8: RMM y REST responden preguntas relacionadas pero diferentes.
Apariencia
Richardson Maturity Model
REST
Propósito
Clasificar las capacidades de la interfaz visible
Definir estilo arquitectónico y propiedades emergentes.
Estructura
Cuatro niveles acumulativos
Conjunto de restricciones combinado
Enfoque
Recursos, HTTP e hipermedia
Componentes, conectores, datos y restricciones.
Resultado
Lenguaje de evaluación y evolución.
Análisis de propiedades arquitectónicas.
Límite
No mide la calidad total ni todas las restricciones.
No prescribe un diseño de punto final único
11.21 , y gobernanza
describe operaciones, parámetros, esquemas, respuestas y mecanismos de seguridad . Es excelente para diseño de contratos, documentación, generación de clientes, burlas y pruebas. Sin embargo, una descripción válida puede representar cualquier nivel: un único con campo de operación, múltiples recursos aún manejados por , una interfaz de nivel 2 u operaciones cuyas respuestas incluyen .
La gobernanza puede utilizar reglas automáticas para detectar signos de niveles: concentración excesiva de , verbos en rutas, falta de respuestas 4xx, creación sin Location, métodos incompatibles con la seguridad, falta de esquemas de error y operaciones sin etiquetas de recursos. Estas reglas son heurísticas. La semántica real, el comportamiento idempotente y la calidad de las relaciones requieren revisión y pruebas humanas.
En los canales empresariales, el análisis debe combinar lint de contrato, pruebas de contrato, pruebas de comportamiento y telemetría. informa lo que se ha declarado; las pruebas verifican lo que ejecuta el tiempo de ejecución; El muestra cómo los consumidores utilizan realmente la interfaz. Una puede documentar e implementar un efecto no idempotente; sólo el comportamiento revela la divergencia.
El contrato no es un comportamiento puede declarar métodos y respuestas correctos mientras la implementación devuelve 200 para todos los errores o cambios de estado en . La madurez debe verificarse mediante pruebas y pruebas operativas.
11.22 Matriz de evaluación
Una revisión útil evita reducir la interfaz a un grado. Para cada viaje, registre la evidencia, el impacto y la acción recomendada. El nivel puede ser informado, pero debe ir acompañado de observaciones sobre , seguridad y funcionamiento. La siguiente tabla proporciona preguntas mínimas que se pueden aplicar a una o un conjunto de puntos finales.
El equipo también debe considerar el peso y el contexto. La ausencia de puede tener un impacto bajo en una interna con dos consumidores estables, mientras que la no idempotente sin deduplicación puede representar un riesgo crítico. La prioridad de mejora debe estar determinada por el riesgo y el valor, no solo por la distancia al nivel 3.
Tabla 9 - Matriz de evaluación basada en evidencia.
Dimensión
Pregunta de evidencia
Pista
Punto final
¿Las intenciones convergen en un único URI genérico?
Nivel 0
Recursos
¿Las entidades y procesos tienen una identidad estable?
Nivel 1
Métodos
¿GET, POST, PUT, PATCH y DELETE respetan la semántica?
Nivel 2
Respuestas
¿Los estados y encabezados permiten una interpretación genérica?
Nivel 2
hipermedia
¿Las representaciones exponen las relaciones y transiciones actuales?
Nivel 3
stateless
¿La solicitud depende de una sesión local previa?
Restricción de REST
caché
¿Las respuestas reutilizables tienen una política explícita?
Restricción de REST
capas
¿El cliente depende de la topología interna?
Restricción de REST
Operación
¿Los registros distinguen gateway, API y dominio?
Calidad operativa
Ejemplo de conclusión de evaluación
Viaje: consulta y cancelación de cita. Evidencia: recursos identificados por /citas/{id}; la lectura usa ; la cancelación utiliza /cancelar; los errores utilizan 200 con sobre. Clasificación: nivel 1 con elementos parciales de nivel 2. Riesgo: observabilidad inconsistente y manejo de . Siguiente acción: adopte o un de cancelación según la semántica del dominio, el estado y los , manteniendo la ruta anterior durante la migración.
11.23 Estrategia de migración
La migración debe comenzar con un viaje de valor y no con una reescritura total del catálogo. Seleccionar operaciones con altos costos de soporte, riesgo de duplicidad o dificultad en la evolución. Consumidores, volúmenes, dependencias de carga útil, códigos internos y políticas del de inventario. Defina métricas de éxito antes de publicar la nueva interfaz.
La nueva superficie puede coexistir con la antigua. Un adaptador traduce mensajes de nivel 0 a recursos y métodos de nivel 2; Las respuestas antiguas se conservan para los clientes heredados. Los contratos tienen fechas, políticas de deprecación y telemetría de uso. Los cambios irreversibles sólo ocurren después de que haya evidencia de migración.
Se debe agregar cuando haya un caso de uso. Comenzar con los enlaces de relaciones propias, siguientes, anteriores y de proceso le permite probar herramientas y consumidores. Se pueden introducir acciones dinámicas en flujos con estados relevantes. El equipo evita crear un marco amplio antes de demostrar el beneficio.
Figura 7: La evolución entre niveles puede ser incremental, compatible y estar impulsada por el riesgo.
11.24 Observabilidad y
La madurez de la interfaz cambia la calidad de las señales operativas. En el nivel 0, las métricas por /servicio agregan todas las intenciones; Es necesario extraer la operación del cuerpo o agregar un atributo comercial. En el nivel 1, las rutas distinguen recursos, pero las acciones pueden permanecer ocultas. En el nivel 2, el método, la plantilla de ruta y el estado ofrecen dimensiones estandarizadas. En el nivel 3, las relaciones seguidas pueden revelar transiciones y viajes.
Los registros deben registrar el método, la plantilla de ruta, el estado, la latencia, el origen de la respuesta, el ID de correlación, el consumidor y el identificador del cuando esté permitido. Evite utilizar el concreto como etiqueta métrica, ya que los ID de alta cardinalidad degradan los sistemas de observabilidad. Utilice /transferencias/{id} como dimensión y conserve el identificador solo en registros o rastreos protegidos.
La debe separar el contrato y el transporte. Se produce un tiempo de espera antes de cualquier clasificación ; un 405 indica que respondió un componente ; un 409 podría representar un conflicto de dominio; un 200 con error interno sugiere contrato de nivel 0 o mal ajuste. Para las puertas de enlace, confirme si la respuesta fue producida por el , la política o el .
Tabla 10 - Síntomas útiles al investigar interfaces en diferentes niveles.
Síntoma
Hipótesis
Pruebas para recoger
Todo aparece como una ruta.
Punto final genérico de nivel 0
campo de operación, política de extracción y rastreo
GET cambia el estado
Semántica de nivel 2 violada
registros de dominio y pruebas repetidas
Reintentar operación de duplicados
POST sin deduplicación
clave de idempotencia y registros transaccionales
El enlace existe pero falla.
Control obsoleto o no autorizado
decisión de representación, estatus y autorización
405 en el gateway
Método bloqueado o no publicado
Allow, configuración de ruta y upstream
200 con problema
Envoltura heredada o transformación
cuerpo, cadena de políticas y estado del backend
11.25 Estudios de casos y laboratorios
Los siguientes ejercicios utilizan un dominio de transferencia ficticio. Ejecútelo solo en laboratorio o en entornos simulados. El objetivo es observar diferencias en contratos y comportamiento; No reproduce datos reales ni integraciones.
Estudio de caso 1: modernización del dispatcher
Una recibe /transacciones con acción=CONSULTAR, acción=CREAR y acción=CANCELAR. Todos los resultados utilizan 200. Proponer recursos, métodos y respuestas. Considere cómo preservar a los antiguos consumidores, cómo correlacionar la nueva transferencia y cómo manejar el tiempo de espera después de la creación. Compara métricas de antes y después.
Estudio de caso 2: proceso asincrónico
Una transferencia puede permanecer bajo revisión. Modele la solicitud como un , devuelva 202 cuando el procesamiento aún no haya finalizado y proporcione un monitor. Luego agregue relaciones propias, de cancelación y de recibo según el estado. Verifique que el servidor rechace acciones no autorizadas incluso cuando el enlace sea fabricado.
Laboratorio 1 - clasificación por evidencia
Enumere todos los puntos finales para una de prueba y agrupe por recorrido.
Identificar operaciones centradas en el cuerpo o verbos en el camino.
Califique cada recorrido, no solo la completa.
Registre evidencia de recursos, métodos, estado, encabezados e .
Producir recomendaciones priorizadas por riesgo y valor.
Laboratorio 2: Prueba de
Ejecute repetidamente y confirme que no se haya solicitado ningún efecto en el dominio.
Repita y y observe el efecto deseado.
Simule actualizaciones simultáneas con e If-Match.
Causar validación, conflicto, ausencia e indisponibilidad; compare el estado y los .
Inspeccione el y el para descubrir qué componente produjo cada respuesta.
Laboratorio 3 - cliente
Comience en un punto de entrada y busque relaciones, sin concatenar caminos.
Realizar únicamente acciones presentes en la .
Cambiar el destino de una relación en el servidor sin modificar el cliente.
Elimine una transición de cambio de estado y observe el comportamiento.
Capture métricas de relaciones seguidas y fallas de transición.
Resumen del capítulo
El modelo de madurez de Richardson describe la evolución en cuatro niveles. El nivel 0 centra las operaciones en mensajes enviados a un genérico. El nivel 1 introduce recursos e identificadores. El nivel 2 utiliza la a través de métodos, estados, encabezados, caché y condiciones previas. El nivel 3 agrega controles que guían las transiciones en el estado actual.
El modelo es útil para diagnóstico y planificación, pero no mide todos los atributos de una plataforma. La seguridad, la confiabilidad, la gobernanza, el rendimiento, la documentación y la compatibilidad requieren su propio análisis. Tampoco reemplaza las restricciones descritas por Fielding. Una interfaz puede alcanzar el nivel 3 sin obtener todas las propiedades arquitectónicas del estilo.
La evolución debe estar impulsada por el riesgo y el valor. Los recursos estables mejoran la identidad; La mejora la interoperabilidad y el funcionamiento; Los pueden reducir el acoplamiento con las y las reglas de flujo. Cada paso tiene costos y depende del ecosistema de consumidores. El objetivo no es lograr una puntuación, sino construir interfaces predecibles, evolutivas y observables.
Lista de verificación de evaluación
¿Las operaciones están concentradas en un y diferenciadas por organismo?
¿Los conceptos de dominio tienen recursos e identificadores estables?
¿Los representan recursos en lugar de nombres de funciones?
¿Los métodos respetan la seguridad y la ?
¿Los códigos de estado identifican correctamente el éxito, el error del cliente y la falla del servidor?
¿Las creaciones, los procesos asincrónicos y las condiciones previas utilizan encabezados adecuados?
¿Los errores tienen un formato estructurado y no exponen datos confidenciales?
¿Los consideran la y la deduplicación?
¿Las representaciones exponen vínculos y acciones con relaciones definidas?
¿Los clientes realmente interpretan las relaciones o continúan codificando las ?
¿La evaluación separa , restricciones y atributos de calidad?
¿El , el y el dominio conservan la misma semántica?
¿Las métricas utilizan plantillas de ruta y distinguen el origen de la respuesta?
¿La migración cuenta con inventario de consumo, telemetría y plan de deprecación?
Ejercicios de repaso
Explique por qué el uso de y no determina el nivel de una .
Clasifique una interfaz con múltiples rutas, todas manejadas por , y justifíquela.
Modelo de consulta, creación y cancelación de transferencias en los niveles 0, 1 y 2.
Describa una situación en la que un nivel 2 es adecuado y el nivel 3 no es adecuado.
Explique cómo e If-Match contribuyen a una interfaz de nivel 2.
Proponer relaciones para un proceso de aprobación de cuatro estados.
Diferenciar entre ausencia de enlace y falta de autorización en el servidor.
Compare con restricciones de caché y .
Explique por qué no certifica el comportamiento idempotente.
Cree un plan de migración para un único utilizado por cinco consumidores.
Describe un script de para 200 que contiene un error interno.
Cree una matriz de evidencia para evaluar una en el y el .
Glosario
Glosario de capítulos esenciales.
Término
Definición
Asequibilidad
Indicación de una posible acción y cómo ejecutarla en el contexto de una representación.
Punto final
Punto de interacción expuesto por una API, normalmente asociado con URI y método.
ODIAOAS
Uso de hipermedia para guiar el estado de la aplicación y las próximas transiciones.
hipermedia
Medios que contienen controles, relaciones o enlaces capaces de guiar la navegación y las acciones.
Idempotencia
Propiedad por la cual repeticiones equivalentes producen el mismo efecto deseado.
relación de enlace
Relación que define el significado de un vínculo entre el contexto y el objetivo.
viruela
XML antiguo y sencillo; en RMM, representa mensajes propietarios transportados por un punto final genérico, incluso cuando el formato moderno es JSON.
Problem Details
Formato estandarizado para representar Problem Details en las API HTTP.
Recurso
Abstracción identificable que puede tener representaciones y estados controlados por el servidor.
Representación
Datos transferidos que describen el estado actual o previsto de un recurso.
Richardson Maturity Model
Modelo de cuatro niveles para observar la adopción de funciones, la semántica HTTP y los hipermedia.
RMM
Acrónimo de Richardson Maturity Model.
Semántica HTTP
Significado compartido de métodos, códigos, encabezados y otros elementos del protocolo.
Plantilla URI
Sintaxis para expresar URI parametrizados que los clientes pueden ampliar.
Enlaces web
Modelo estandarizado para expresar enlaces y relaciones en mensajes web.
Referencias técnicas
Las referencias siguientes deben leerse juntas. El artículo de Fowler presenta el modelo; La disertación de Fielding proporciona la base arquitectónica de ; Los definen la semántica interoperable utilizada en los ejemplos.
[1] FOWLER, Martín. : pasos hacia la gloria de . 2010. Disponible en: martinfowler.com/articles/richardsonMaturityModel. .
[2] FIELDING, Roy Thomas. Estilos arquitectónicos y diseño de arquitecturas de software basadas en red. Universidad de California, Irvine, 2000. Capítulo 5: Transferencia estatal representativa.
[3] . 9110 - . 2022.
[4] . 9111: almacenamiento en caché . 2022.
[5] . 8288 - . 2017.
[6] . 6570 - . 2012.
[7] . 9457: para las . 2023.
[8] . Registro de Relaciones de Enlace. Registro de relaciones estandarizadas para enlaces.
[9] Iniciativa . Especificación de . Especificación para describir las .
[10] . 6902: parche de notación de objetos JavaScript ( ). 2013.
[11] . 7386: parche de fusión . 2014.
[12] . 7232 - Protocolo de transferencia de hipertexto ( /1.1): Solicitudes condicionales. 2014. Obsoleto como documento agregado, pero históricamente relevante; La semántica actual está consolidada en 9110.
del capítulo El siguiente paso del curso es profundizar en la descripción y gobernanza de los contratos , conectando el modelado , , validación, compatibilidad y automatización de .
