¿Qué es el modelo de madurez de API?

Algunos marcos de madurez de las API hacen hincapié en aspectos concretos como la seguridad, la facilidad de descubrimiento, la capacidad de mantenimiento o la ingeniería de plataforma. Los proveedores de gestión de API, incluidos Kong, Tyk y Curity, ofrecen modelos de madurez de API alineados con sus propias soluciones, lo que ayuda a los clientes a medir su progreso en la adopción de esas plataformas. Otros modelos tienen un alcance más amplio y se pueden aplicar a cualquier protocolo o arquitectura.

Las interfaces de programación de aplicaciones (API), que facilitan las conexiones entre servicios y aplicaciones independientes, son un pilar clave de Internet, ya que ayudan a los desarrolladores a utilizar tecnologías y fuentes de datos de terceros, en lugar de construirlas desde cero. También permiten la integración de recursos, datos, seguridad y gobernanza dentro de las organizaciones, agilizando los despliegues internos y las comunicaciones entre equipos. Se pueden incluir varias API junto con bibliotecas, herramientas de interfaz de usuario (IU) y otros componentes para formar un kit de desarrollo de software (SDK), un conjunto de herramientas que ayuda a los desarrolladores a crear aplicaciones estandarizadas de forma rápida y confiable.

Los modelos de madurez de las API identifican y describen innovaciones estructurales y tecnológicas específicas, así como las mejores prácticas estratégicas que pueden ayudar a las organizaciones a desarrollar sistemas de API más sofisticados y robustos, mejorando así la eficiencia, la seguridad y la interoperabilidad. Sirven como una hoja de ruta que ayuda a las organizaciones a decidir qué innovaciones priorizar a medida que aceleran el desarrollo de sus API.

El modelo de madurez de Richardson, uno de los entornos más citados, evalúa la adherencia de una API a los principios RESTful en cuatro niveles de madurez, y el nivel más alto representa un sistema RESTful completamente.

En 2000, el científico informático Roy Fielding introdujo REST, un estilo arquitectónico que promueve características como una interfaz uniforme, desacoplamiento cliente-servidor, sin estado, capacidad en caché y sistemas en capas. En conjunto, estas capacidades pueden mejorar la escalabilidad, la eficiencia y la flexibilidad dentro de las organizaciones, y pueden contribuir a una Internet más abierta, resiliente y segura cuando se implementan a mayor escala. Las iteraciones modernas a menudo usan HTTP para transportar información y el formato JSON legible por humanos para organizar estos datos, aunque también se pueden usar otros protocolos y formatos.

En 2008, el ingeniero de software Leonard Richardson se basó en este marco con un modelo que identifica cambios técnicos específicos que las organizaciones pueden implementar para mejorar la adaptabilidad y resiliencia de su diseño de API REST. El modelo de madurez de Richardson (RMM) “incentiva a mirar las tres tecnologías web —URI, HTTP e hipermedia (también conocida como HTML)— como tres tecnologías individuales en lugar de un acuerdo de paquete”, dijo Richardson a IBM Think. El marco muestra los beneficios prácticos de implementar progresivamente cada una, “dado que tenemos estas tecnologías, son muy populares y son ampliamente compatibles con todos los lenguajes de programación”.

El modelo de madurez de Richardson prioriza la implementación de recursos, donde a cada recurso se le asigna un URI distinto, de acuerdo con los principios generales de REST, que recomiendan asignar a cada recurso una identificación única. El RMM también fomenta el uso de documentos de respuesta, que capturan el estado actual de una API, en lugar de documentos de descripción, que presentan una descripción estática y predefinida de una API en un solo momento. El modelo se aplica generalmente a aplicaciones web basadas en HTTP, aunque, como marco conceptual, también puede utilizarse en otros contextos, como las redes del IoT y los pipelines de datos.

El modelo de madurez de Richardson usa cuatro niveles para distinguir entre diferentes grados de madurez, desde una arquitectura que no es de RESTful hasta una completamente RESTful.

El nivel cero representa un diseño que no es de RESTful, con un único endpoint (como “/api”) y un único comando (normalmente POST). Si bien el nivel cero es fácil de implementar, no utiliza las características más potentes de HTTP, incluidos verbos, URI y códigos de estado. En cambio, HTTP se utiliza simplemente como un mecanismo de transporte, con todos los detalles operativos agregados al propio cuerpo del mensaje.

Debido a que los patrones de llamada a procedimiento remoto (RPC) basados en XML han empleado históricamente este método, los críticos lo han apodado “pantano de POX” (el XML simple de siempre). La idea es que, ante la falta de estructura y sin delimitaciones claras entre los servicios, las funciones y los datos pueden llegar a desorganizarse fácilmente y quedar estrechamente entrelazados. En el nivel cero, la API no tiene capacidad para identificar o exponer recursos detectables, lo que obliga a los consumidores de API a saber de antemano qué está disponible. Los desarrolladores pueden tener dificultades con el escalado, el control de versiones y la resolución de problemas porque el endpoint único no puede compartir información sobre sí mismo.

El nivel uno introduce múltiples URI, cada uno capaz de representar un recurso diferente. Pero continúa usando un solo verbo HTTP, generalmente POST. En lugar de interactuar con un endpoint genérico “/api”, los clientes ahora pueden llamar a endpoints que corresponden a recursos específicos, por ejemplo, “/productos,” “/carritos” o “/facturas” en un entorno de comercio electrónico. Sin embargo, los clientes suelen necesitar transmitir la intención operativa o las acciones a través del cuerpo de la propia solicitud, en lugar de utilizar un conjunto predefinido de verbos HTTP.

Este enfoque establece líneas más limpias entre los recursos y reduce las ambigüedades en torno a qué recursos están disponibles para los clientes. Pero los desarrolladores pueden confundir fácilmente qué acciones se pueden realizar porque no existe un formato estandarizado para llamar a los URI. El nivel uno también puede volverse engorroso con el tiempo porque, en la práctica, los desarrolladores pueden crear nuevos endpoints para acciones individuales, como “/productsUpdate” o “/productsDelete”. Este enfoque puede hacer que los URI se acumulen gradualmente, lo que dificulta los despliegues y el control de versiones.

Por último, el modelo hace que los desarrolladores dependan más de la documentación de API externa porque, aunque a los recursos se les asignan URI distintos, no pueden exponer qué acciones se pueden interpretar o cumplir.

El nivel dos agrega métodos HTTP, un conjunto estandarizado de verbos que los desarrolladores pueden usar para interactuar con datos y servicios. En muchas configuraciones, los clientes pueden usar cuatro comandos básicos (crear, leer, actualizar o eliminar) para realizar diferentes acciones en cada endpoint. Los encabezados se pueden utilizar para transmitir información adicional, como el tipo de contenido, los requisitos condicionales o las credenciales de autorización, durante la llamada a la API.

Este enfoque es más eficiente y organizado en comparación con el nivel uno y el nivel cero porque los usuarios tienen una idea de lo que la API es capaz de hacer y cómo los clientes pueden interactuar con ella. Pero las API no pueden transmitir esta información en tiempo real: los usuarios solo pueden aprender sobre cada API a través de un portal de desarrolladores, lo que reduce la capacidad de descubrimiento. Este enfoque estático también puede provocar desalineaciones si la documentación de la API no coincide con las capacidades actuales.

Hoy en día, los ecosistemas de API de la mayoría de las organizaciones operan en el nivel dos porque el nivel ofrece un equilibrio entre previsibilidad, eficiencia y accesibilidad. También permite a las organizaciones aprovechar las distintas capacidades de infraestructura de HTTP, como el almacenamiento en caché (almacenar localmente los recursos de uso frecuente, para que puedan recuperarse de manera rápida), lo que genera importantes ganancias de rendimiento.

El nivel tres introduce HATEOAS, o hipermedia como motor del estado de la aplicación. Cuando un cliente realiza una llamada a la API, la API responderá con una lista dinámica de opciones para varias acciones y términos relacionados, como el funcionamiento de los navegadores modernos. Estas acciones y términos se transmiten en banda, lo que significa que los desarrolladores no tienen que consultar documentación externa para conocerlos. Las arquitecturas basadas en hipermedia también fomentan la interoperabilidad, ya que los clientes externos pueden acceder fácilmente a los servicios sin necesidad de aprender a utilizarlos de antemano.

Al mismo tiempo, los controles de hipermedia introducen mayor complejidad en tiempo de ejecución: “El cliente tiene que ser capaz no solo de reaccionar de manera preprogramada, sino poder leer los documentos que están llegando desde el servidor y utilizar el contenido de esos documentos para tomar la decisión sobre su próxima solicitud”, dijo Richardson.

Construir y mantener capacidades de hipermedia puede ser más costoso y llevar más tiempo debido a la estructura dinámica de la hipermedia. La API responde a las solicitudes de los clientes con un conjunto de enlaces para realizar acciones adicionales, lo cual supone una mayor carga operativa. Además, muchas plataformas de clientes no admiten hipermedia, por lo que cuando una organización adopta HATEOAS, es posible que los usuarios externos tengan que encontrar herramientas compatibles antes de poder acceder a estos servicios.

Hoy en día, HATEOAS se utiliza con mayor frecuencia en bibliotecas, organizaciones sin fines de lucro, instituciones científicas, coaliciones de mercado o empresas insurgentes (organizaciones que intentan irrumpir en una industria), señaló Richardson, porque promueve la apertura y la interoperabilidad. La hipermedia también puede ser eficaz cuando se usa internamente porque hace que las API y las acciones sean fácilmente detectables para los usuarios, incluso para los usuarios que no tienen conocimiento previo del ecosistema de API. Es posible que algunas empresas ofrezcan API de hipermedia durante su fase de crecimiento y, posteriormente, restrinjan el acceso una vez que comienzan a monetizar su producto.

La industria está recurriendo cada vez más a alternativas como GraphQL y gRPC para casos de uso. Si bien el 93 % de los desarrolladores dice que usa servicios web RESTful de alguna manera, según el informe State of the API de Postman, un tercio ahora usa GraphQL y el 14 % usa gRPC. GraphQL puede obtener de forma inteligente solicitudes de múltiples microservicios, incluso servicios alojados en diferentes entornos, y compilarlas en una única respuesta, lo que aumenta la eficiencia y evita el aprovisionamiento excesivo o insuficiente. Mientras tanto, gRPC es ideal para transmisión, telemetría y otros casos de uso donde el alto rendimiento y la baja latencia son las principales preocupaciones.

Aunque GraphQL y gRPC no pueden replicar la naturaleza dinámica de la hipermedia, ambas arquitecturas abordan con mayor precisión los puntos débiles relacionados con la eficiencia y la gestión de esquemas, lo que lleva a algunas organizaciones a priorizar estas implementaciones sobre los controles completos de hipermedia.

En el modelo de madurez de Richardson, pasar de un nivel de madurez de API al siguiente puede presentar desafíos tanto de diseño como técnicos. El proceso suele implicar la refactorización del código del servidor para dar cabida a múltiples URI (nivel uno) y múltiples métodos HTTP (nivel dos). Esto se logra actualizando las reglas de enrutamiento, las interacciones de bases de datos, las pruebas, la documentación y los controladores.

Las organizaciones pueden comenzar por catalogar sus endpoints actuales, identificar cuáles se pueden modificar para seguir las restricciones RESTful y mapear los recursos y verbos necesarios. Los desarrolladores pueden crear una nueva versión basada en la versión actual de la organización, de modo que las llamadas de los clientes no se vean interrumpidas durante la transición. Un conjunto completo de códigos de error también puede ayudar a los usuarios a aprender a navegar por nuevos endpoints de API y solucionar errores sin consultar documentación excesiva.

Si bien el RMM se centra en implementaciones tecnológicas específicas en sistemas RESTful, los modelos organizacionales adoptan una visión más amplia, ayudando a las empresas a alinearse en torno a un conjunto compartido de principios que fomentan la coherencia, la optimización de recursos y la adaptabilidad. Si bien los marcos de madurez estratégica pueden diferir según la organización, un enfoque común incorpora cuatro niveles:

En los ecosistemas de API básicos o ad hoc, las organizaciones reaccionan a las preocupaciones inmediatas en lugar de trabajar bajo un marco cohesivo de desarrollo de API. Los desarrolladores crean y retiran las API según sea necesario con un control centralizado limitado, lo que puede provocar desalineaciones, así como problemas de control, seguridad y observabilidad. Sin un insight claro del rendimiento actual de las API, los equipos no pueden asignar recursos de manera eficaz ni planificar el futuro.

Los ecosistemas de API estandarizados introducen documentación coherente, convenciones de nomenclatura, códigos de error y patrones de diseño. Se puede usar una API gateway para aplicar la autenticación, la autorización y otros protocolos de seguridad de API centralizados. Los desarrolladores pueden agregar, eliminar y mantener API con confianza dentro de la estructura de gobernanza de la organización y pueden reutilizar y adaptar componentes perfectamente. Los clientes pueden descubrir y aprender fácilmente sobre los servicios disponibles a través de un portal de desarrolladores y la incorporación integrada, lo que aumenta la adopción general de API.

Pero debido a que hay pocos mecanismos para capturar el rendimiento y la seguridad de las API en esta etapa, los equipos pueden tener dificultades para mantener la supervisión del ecosistema. Por ejemplo, una organización puede desconocer las violaciones de seguridad, los errores de control de versiones o los problemas de autenticación dentro de un clúster de API en particular.

Los marcos gestionados utilizan datos de telemetría, KPI y otras métricas para capturar el rendimiento de la API con mayor detalle. Por ejemplo, un sistema de monitoreo puede alertar a los desarrolladores cuando los clientes enfrentan un tiempo de inactividad excesivo de la API y ayudar a identificar el problema subyacente, ya sea una sobrecarga del servidor, interrupciones en la red, errores en el código u otro problema.

Los ecosistemas gestionados también podrían contar con una característica más avanzada de gobernanza de API, que preserva la autonomía del equipo y proporciona a los stakeholders una comprensión clara de qué API son responsables de gestionar. Por último, los ecosistemas gestionados incorporan procesos formales de gestión del ciclo de vida, en los que se supervisa el uso de las API a lo largo de todas las fases: diseño, desarrollo, mantenimiento, control de versiones y retiro. Pero en este nivel, es posible que las organizaciones aún carezcan de una visión cohesiva de cómo la gestión de API contribuye a objetivos comerciales más amplios.

Los marcos optimizados o estratégicos combinan la gobernanza, la estandarización, la gestión del ciclo de vida, las métricas y las mejores prácticas de seguridad con la planificación empresarial a largo plazo. Al tener una visión global de toda la red, las organizaciones pueden escalar y asignar recursos de manera eficiente, así como responder de forma dinámica a las condiciones cambiantes del mercado. En lugar de pensar en las API solo como componentes técnicos, las organizaciones pueden desplegar API al servicio de objetivos comerciales más amplios. Los marcos estratégicos ayudan a las organizaciones a elaborar hojas de ruta y estrategias de planificación con visión de futuro, acelerando la innovación y mejorando la eficiencia operativa.

Las organizaciones pueden elaborar modelos de madurez de API para abordar puntos débiles específicos o enfoques operativos. Las áreas de enfoque comunes incluyen:

Estos modelos de madurez se centran en los principios de diseño de API, como la adopción de protocolos, prácticas y estándares específicos que contribuyen a una mejor experiencia de usuario. El RMM es un ejemplo de un marco basado en el diseño, pero otros modelos podrían centrarse en GraphQL, gRPC y otros estilos arquitectónicos.

Los modelos de gobernanza se centran en la capacidad de las organizaciones para mantener el control y la supervisión de sus ecosistemas de API. En los niveles más altos, las organizaciones mantienen un alto cumplimiento, calidad de datos y seguridad, al tiempo que preservan la autonomía de los stakeholders.

Los marcos basados en la gobernanza también consideran la calidad de los mecanismos de aplicación de un ecosistema de API, incluso si incorpora verificaciones automatizadas y procesos de validación. Por su parte, los modelos de responsabilidad asignan las API a equipos específicos, de modo que se tenga un control sobre cada una de ellas.

Los marcos de madurez centrados en la seguridad evalúan la adherencia de una red API a las mejores prácticas de seguridad. En las primeras etapas, las organizaciones pueden confiar en claves API o autenticación HTTP básica, que carecen de control granular y son vulnerables a la exposición. Los sistemas avanzados pueden introducir autenticación y autorización basadas en token, así como acceso de confianza cero. Los marcos más sofisticados se ajustan a los principios de gestión de identidad y acceso, como el uso de los protocolos de autorización OAuth y OpenID Connect (OIDC).

Los documentos de API son guías técnicas que proporcionan instrucciones sobre cómo los desarrolladores pueden usar e integrar una API en particular. La documentación puede incluir tutoriales y ejemplos de código, así como notas de la versión y parámetros de llamada aceptables.

Inicialmente, es posible que las organizaciones no tengan un proceso estandarizado para crear y mantener la documentación de API, lo que brinda a los desarrolladores poco insight sobre lo que es capaz de hacer cada API. Los niveles más altos pueden introducir formatos estandarizados para describir las especificaciones de API, como OpenAPI Specification (OAS) o API Blueprint. Los marcos de API maduros también pueden incorporar automatización, lo que ayuda a garantizar que la documentación se actualice automáticamente junto con cada implementación.

Los modelos de madurez centrados en la observabilidad ayudan a las organizaciones a hacer un seguimiento del nivel de sofisticación de sus mecanismos de recopilación de datos en todos los microservicios. Los sistemas básicos pueden usar telemetría y métricas para ayudar a las organizaciones a detectar errores, pero no pueden ayudar a identificar tendencias de datos a largo plazo.

Las plataformas más complejas pueden realizar un seguimiento proactivo de la latencia, las tasas de solicitudes y otras métricas relevantes para ayudar a las organizaciones a anticiparse a los tiempos de inactividad, las descoordinaciones y otros problemas. En el nivel más alto, las organizaciones pueden identificar patrones de datos de alto nivel y generar insights aplicables en la práctica que guían el desarrollo de API.