¿Qué es el modelo de madurez de API?

Algunos marcos de madurez de API hacen hincapié en aspectos concretos como la seguridad, la descubribilidad, el mantenimiento o la ingeniería de plataformas. 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 crearlas desde cero. También permiten la integración de recursos, datos, seguridad de datos y gobierno dentro de las organizaciones, agilizando las implementaciones internas y las comunicaciones entre equipos. Se pueden agrupar varias API junto con bibliotecas, herramientas de 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 fiable.

Los modelos de madurez de las API identifican y describen las innovaciones estructurales y tecnológicas específicas, así como buenas prácticas estratégicas que pueden ayudar a las organizaciones a desarrollar sistemas de API más sofisticados y robustos, mejorando 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 marcos 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 totalmente RESTful.

En 2000, el informático Roy Fielding presentó REST, un estilo arquitectónico que promueve características como una interfaz uniforme, la separación entre cliente y servidor, la ausencia de estado, la capacidad de almacenamiento en caché y los sistemas en capas. Juntas, 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 versiones actuales suelen utilizar HTTP para transmitir información y el formato JSON, legible para los humanos, para organizar estos datos, aunque también pueden emplearse otros protocolos y formatos.

En 2008, el ingeniero de software Leonard Richardson amplió este marco con un modelo que identifica cambios técnicos específicos que las organizaciones pueden implementar para mejorar la adaptabilidad y la resiliencia del diseño de sus API REST. El modelo de madurez de Richardson (RMM) “le anima a considerar las tres tecnologías web (URI, HTTP e hipermedia, también conocida como HTML) como tres tecnologías individuales en lugar de un paquete”, declaró Richardson a IBM® Think. El marco pone de manifiesto los beneficios prácticos de implementar cada una de ellas de forma progresiva, “dado que contamos estas tecnologías, que gozan de gran popularidad 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 único momento. El modelo se aplica generalmente a aplicaciones web basadas en http, aunque como marco conceptual también puede usarse en otros contextos, como redes de IoT y pipelines de datos.

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

El nivel cero representa un diseño no RESTful, que cuenta con un único endpoint (como “/api”) y un único comando (normalmente POST). Aunque el nivel cero es sencillo de implementar, no utiliza las características más potentes de HTTP, entre las que se incluyen los verbos, los URI y los códigos de estado. En su lugar, HTTP se utiliza simplemente como mecanismo de transporte, con todos los detalles operativos añadidos al propio cuerpo del mensaje.

Dado que los patrones de llamada a procedimientos remotos (RPC) basados en XML han empleado históricamente este método, los críticos lo han apodado “el pantano del POX” (plain old XML). La idea es que, al carecer de estructura y de delimitaciones claras entre los servicios, las funciones y los datos pueden llegar fácilmente a estar desordenados y estrechamente acoplados. En el nivel cero, la API no tiene capacidad para identificar ni exponer recursos detectables, lo que obliga a los usuarios de la API a saber de antemano qué hay disponible. Los desarrolladores pueden tener dificultades con el escalado, el control de versiones y la resolución de problemas, ya que el único endpoint no puede compartir información sobre sí mismo.

El nivel uno introduce múltiples URI, cada una de las cuales puede representar un recurso diferente. Sin embargo, sigue utilizando un único verbo HTTP, normalmente 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, “/products”, “/carts” o “/invoices” en un entorno de comercio electrónico. Sin embargo, los clientes suelen seguir necesitando 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 provocar que los URI se acumulen gradualmente, lo que complica los lanzamientos y el control de versiones.

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

El nivel dos incorpora los métodos HTTP, un conjunto estandarizado de verbos que los desarrolladores pueden utilizar para interactuar con datos y servicios. En muchas configuraciones, los clientes pueden utilizar cuatro comandos básicos (crear, leer, actualizar o eliminar) para realizar diferentes acciones en cada endpoint. Los encabezados pueden utilizarse 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 obtener información sobre cada API a través de un portal para desarrolladores, lo que reduce la descubribilidad. Este enfoque estático también puede dar lugar a desajustes si la documentación de la API no se corresponde con las capacidades actuales.

En la actualidad, los ecosistemas de API de la mayoría de las organizaciones operan en el nivel dos porque este nivel ofrece un equilibrio entre previsibilidad, eficacia y accesibilidad. También permite a las organizaciones beneficiarse de las distintas capacidades de infraestructura de HTTP, como el almacenamiento en caché (almacenar localmente los recursos de uso frecuente para poder recuperarlos rápidamente), lo que se traduce en importantes mejoras de rendimiento.

El nivel tres introduce HATEOAS, es decir, el hipermedia como motor del estado de la aplicación. Cuando un cliente realiza una llamada a la API, esta 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 de antemano cómo utilizarlos.

Al mismo tiempo, los controles hipermedia introducen una mayor complejidad en tiempo de ejecución: “El cliente no solo debe ser capaz de reaccionar de una manera preprogramada, sino también de leer los documentos que llegan desde el servidor y utilizar el contenido de dichos documentos para tomar la decisión sobre su siguiente solicitud”, afirmó Richardson.

La creación y el mantenimiento de capacidades hipermedia pueden resultar más costosos y llevar más tiempo debido a la estructura dinámica de la hipermedia. La API responde a las solicitudes del cliente con un conjunto de enlaces para acciones posteriores, lo que supone una mayor carga operativa. Además, muchas plataformas de clientes no son compatibles con el hipermedia, por lo que, cuando una organización adopta HATEOAS, es posible que los usuarios externos tengan que buscar herramientas compatibles antes de poder acceder a estos servicios.

En la actualidad, HATEOAS es utilizado con mayor frecuencia por bibliotecas, organizaciones sin ánimo de lucro, instituciones científicas, coaliciones de mercado o empresas disruptivas (organizaciones que intentan revolucionar un sector), según Richardson, ya que promueve la apertura y la interoperabilidad. La hipermedia también puede resultar eficaz cuando se utiliza internamente, ya que facilita a los usuarios la localización de las API y las acciones, incluso a aquellos que carecen de conocimientos previos sobre el ecosistema de las API. Algunas empresas pueden ofrecer API de hipermedia durante su fase de crecimiento y, posteriormente, restringir el acceso una vez que comienzan a monetizar su producto.

El sector está recurriendo cada vez más a alternativas como GraphQL y gRPC para casos de uso concretos. Aunque el 93 % de los desarrolladores afirman utilizar servicios web RESTful de alguna forma, según el informe State of the API de Postman, un tercio utiliza ahora GraphQL y el 14 % utiliza gRPC. GraphQL puede recuperar de forma inteligente solicitudes de múltiples microservicios, incluso de servicios alojados en entornos diferentes, y compilarlas en una única respuesta, lo que aumenta la eficiencia y evita el sobreaprovisionamiento o el subaprovisionamiento. Por su parte, gRPC es ideal para el streaming, la telemetría y otros casos de uso en los que el alto rendimiento y la baja latencia son las principales preocupaciones.

Aunque GraphQL y gRPC no pueden reproducir la naturaleza dinámica de la hipermedia, ambas arquitecturas abordan con mayor precisión los problemas relacionados con la eficiencia y la gestión de esquemas, lo que lleva a algunas organizaciones a dar prioridad a estas implementaciones frente a los controles completos de hipermedia.

En el modelo de madurez de Richardson, pasar de un nivel de madurez de API al siguiente puede plantear retos 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 consigue actualizando las reglas de enrutamiento, las interacciones con la base de datos, las pruebas, la documentación y los controladores.

Las organizaciones podrían comenzar por catalogar sus endpoints actuales, identificando cuáles pueden modificarse para cumplir con las restricciones RESTful y definiendo los recursos y verbos necesarios. Los desarrolladores podrían crear una nueva versión basada en la 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 familiarizarse con los nuevos endpoints de la API y a resolver los errores sin tener que consultar una documentación excesiva.

Mientras que el RMM se centra en implementaciones tecnológicas específicas en sistemas RESTful, los modelos organizativos 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. Aunque los marcos de madurez estratégica pueden variar según la organización, un enfoque común incorpora cuatro niveles:

En ecosistemas de API básicos o ad hoc, las organizaciones reaccionan a 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 desajustes y problemas de gobierno, seguridad y observabilidad. Con poca perspectiva sobre el rendimiento actual de la API, los equipos no pueden asignar recursos de manera efectiva ni planificar el futuro.

Los ecosistemas de API estandarizados aportan documentación coherente, convenciones de nomenclatura, códigos de error y patrones de diseño. Se puede utilizar una puerta de enlace de API para aplicar la autenticación, la autorización y otros protocolos de seguridad de API centralizados. Los desarrolladores pueden añadir, eliminar y mantener API con confianza dentro de la estructura de gobierno de la organización y pueden reutilizar y adaptar componentes de manera fluida. Los clientes pueden descubrir y conocer fácilmente los servicios disponibles a través de un portal para desarrolladores y un proceso de incorporación integrado, lo que aumenta la adopción general de la API.

Sin embargo, dado que en esta fase existen pocos mecanismos para evaluar el rendimiento y la seguridad de las API, es posible que a los equipos les resulte difícil mantener el control sobre el ecosistema. Por ejemplo, una organización podría desconocer la existencia de violaciones de seguridad, errores de versionado o problemas de autenticación dentro de un clúster de API concreto.

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 monitorización puede alertar a los desarrolladores cuando los clientes se enfrentan a un tiempo de inactividad excesivo de la API y ayudar a identificar el problema subyacente, ya sea una sobrecarga de servidores, interrupciones de la red, desajustes de código u otro problema.

Los ecosistemas gestionados también pueden contar con una infraestructura de gobierno de API más avanzada, que preserva la autonomía del equipo y ofrece a las partes interesadas una comprensión clara de qué API son responsables de gestionar. Por último, los ecosistemas gestionados introducen procesos formales de gestión del ciclo de vida, en los que las API se monitorizan a lo largo del diseño, el desarrollo, el mantenimiento, el control de versiones y la retirada. Pero en este nivel, las organizaciones aún pueden carecer de una visión cohesiva de cómo la gestión de API contribuye a objetivos empresariales más amplios.

Los marcos estratégicos combinan las buenas prácticas de gobierno, estandarización, gestión del ciclo de vida, métricas y seguridad con la planificación de negocio a largo plazo. Con la supervisión de toda la red, las organizaciones pueden escalar y asignar recursos eficazmente y responder de forma dinámica a las cambiantes condiciones del mercado. En lugar de pensar en las API solo como componentes técnicos, las organizaciones pueden implementarlas al servicio de objetivos empresariales 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 las API para abordar problemas concretos o prioridades operativas. Entre las áreas de interés más habituales se 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 mejorar la experiencia del usuario. El RMM es un ejemplo de marco basado en el diseño, pero otros modelos podrían centrarse en GraphQL, gRPC y otros estilos arquitectónicos.

Los modelos de gobierno se centran en el grado en que las organizaciones pueden mantener el control y la supervisión sobre sus ecosistemas de API. En los niveles más altos, las organizaciones mantienen un alto cumplimiento, la calidad de los datos y la seguridad, a la vez que preservan la autonomía de las partes interesadas.

Los marcos basados en el gobierno también consideran la calidad de los mecanismos de aplicación de un ecosistema de API, incluyendo si incorpora procesos automatizados de comprobación y validación. Por su parte, los modelos de propiedad asignan las API a equipos específicos, de modo que se tenga constancia de todas ellas.

Los marcos de madurez centrados en la seguridad evalúan la adhesión de una red API a las buenas prácticas de seguridad. En las primeras etapas, las organizaciones pueden confiar en las claves API o en la autenticación HTTP básica, que carecen de control granular y son vulnerables a la exposición. Los sistemas avanzados podrían incorporar la autenticación y la autorización basadas en tokens, así como el acceso zero trust. Los marcos más sofisticados se adhieren a los principios de gestión de identidades y accesos, 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 versión y parámetros de llamada aceptables.

Al principio, es posible que las organizaciones no cuenten con un proceso estandarizado para crear y mantener la documentación de las API, lo que limita la perspectiva de los desarrolladores sobre las capacidades de cada API. Los niveles superiores pueden introducir formatos estandarizados para describir las especificaciones de las API, como la especificación OpenAPI (OAS) o API Blueprint. Los marcos de API maduros también pueden incorporar automatización, ayudando 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 realizar un seguimiento de la sofisticación de sus mecanismos de recopilación de datos en los microservicios. Los sistemas básicos pueden utilizar la telemetría y las 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 responder con antelación a los tiempos de inactividad, los desajustes y otros problemas. En el nivel más alto, las organizaciones pueden identificar patrones de datos de alto nivel y generar perspectivas procesables que guíen el desarrollo futuro de API.