Las ventajas de un enfoque API-first para crear microservicios

NGINX | 19 de enero de 2023

Las API son el tejido conectivo de las aplicaciones nativas de la nube: el medio por el que se comunican los microservicios que componen una aplicación. A medida que las aplicaciones crecen y escalan, también aumenta el número de microservicios y API. Aunque en la mayoría de los casos esto es inevitable, plantea importantes retos para los equipos de operaciones de plataforma responsables de garantizar la fiabilidad, la escalabilidad y la seguridad de las aplicaciones modernas. Denominamos este problema proliferación de API y ya hablamos de él en una entrada anterior del blog.

Como primer intento para resolver la proliferación de API, una organización podría optar por un enfoque descendente mediante la implementación de herramientas para automatizar la detección y corrección de API. Aunque esto resulta eficaz a corto plazo, suele imponer una carga excesiva a los equipos responsables de crear y operar API y microservicios. Estos equipos deben reelaborar los microservicios y las API existentes para solucionar problemas de seguridad y cumplimiento normativo, o bien someterse a un arduo proceso de revisión para obtener las aprobaciones necesarias. Por este motivo, muchas grandes organizaciones de software adoptan un enfoque descentralizado que utiliza la gobernanza adaptativa para dar a los desarrolladores la autonomía que necesitan.

En lugar de implementar medidas de protección de última hora, un enfoque ascendente del problema resulta más eficaz a largo plazo. Los equipos que crean y gestionan las API de los distintos microservicios y aplicaciones son los primeros en participar y, a menudo, comienzan adoptando un enfoque de desarrollo de software basado en API-first en su organización.

¿Qué es API-First?

Las API existen desde hace décadas. Pero ya no son simplemente «interfaces de programación de aplicaciones». En esencia, las API son interfaces para desarrolladores. Como cualquier interfaz de usuario, requieren planificación, diseño y pruebas. El enfoque API-first consiste en reconocer y priorizar la importancia de la conectividad y la sencillez en todos los equipos que gestionan y utilizan API. Da prioridad a la comunicación, la reutilización y la funcionalidad para los consumidores de API, que casi siempre son desarrolladores.

Hay muchos caminos para adoptar un enfoque API-first, pero el objetivo final de la mayoría de las empresas que emprenden este camino es adoptar un enfoque de desarrollo de software basado en el diseño. En la práctica, este enfoque implica definir por completo las API antes de implementarlas. El trabajo comienza diseñando y documentando cómo funcionará la API. El equipo se basa en el artefacto resultante, a menudo denominado «contrato de API», para determinar cómo implementar las funcionalidades de la aplicación.

Descubre técnicas de diseño para respaldar un enfoque API-first del desarrollo de software que sea sólido y flexible en el capítulo 1 del libro electrónico «Mastering API Architecture» de O’Reilly, cortesía de NGINX.

El valor del enfoque API-first para las organizaciones

Una estrategia API-first suele ser ideal para las arquitecturas de microservicios, ya que garantiza que los ecosistemas de aplicaciones se conciban desde el principio como sistemas modulares y reutilizables. Adoptar un modelo de desarrollo de software API-first ofrece importantes ventajas tanto para los desarrolladores como para las organizaciones, entre ellas:

Mayor productividad de los desarrolladores – Los equipos de desarrollo pueden trabajar en paralelo y actualizar las aplicaciones de backend sin afectar a los equipos que trabajan en otros microservicios que dependen de las API de dichas aplicaciones. La colaboración suele ser más sencilla durante todo el ciclo de vida de las API, ya que todos los equipos pueden consultar el contrato de API establecido.
Experiencia del desarrollador mejorada – El diseño API-first prioriza la experiencia del desarrollador al garantizar que una API sea lógica y esté bien documentada. Esto permite a los desarrolladores interactuar con ella de forma fluida. Descubre por qué es tan importante que los equipos de operaciones de plataforma tengan en cuenta la experiencia del desarrollador de API<.htmla>.
Gobernanza y seguridad coherentes – Los arquitectos de la nube y de plataformas pueden organizar el ecosistema de API de forma coherente incorporando reglas de seguridad y gobernanza durante la fase de diseño de la API. Esto evita las costosas revisiones necesarias cuando los problemas se detectan en fases posteriores del proceso de desarrollo de software.
Mejora de la calidad del software – Diseñar primero las API garantiza que los requisitos de seguridad y cumplimiento se satisfagan en una fase temprana del proceso de desarrollo, mucho antes de que la API esté lista para implementarse en producción. Al reducirse la necesidad de corregir vulnerabilidades de seguridad en producción, los equipos de operaciones, calidad e ingeniería de seguridad disponen de más tiempo para trabajar directamente con los equipos de desarrollo y garantizar que los estándares de calidad y seguridad se cumplan durante la fase de diseño.
Menor tiempo de comercialización – Al haber menos dependencias y contar con un marco coherente para la comunicación entre servicios, los distintos equipos pueden crear y mejorar sus servicios de forma mucho más eficiente. Una especificación de API coherente y legible por máquinas es una herramienta que puede ayudar a los desarrolladores y a los equipos de operaciones de plataforma a colaborar mejor.

En general, adoptar un enfoque API-first puede ayudar a una empresa a crear una arquitectura de microservicios más flexible, escalable y segura.

Cómo puede ayudar la adopción de una especificación común para las API

En el entorno habitual de microservicios y API empresariales, intervienen más componentes de los que un equipo de operaciones de plataforma puede controlar en su día a día. Adoptar una especificación de API estándar y legible por máquinas ayuda a los equipos a comprender y supervisar las API que operan actualmente en sus entornos, así como a tomar decisiones sobre ellas.

Adoptar una especificación de API común también puede ayudar a mejorar la colaboración con las partes interesadas durante la fase de diseño de la API. Al crear un contrato de API y formalizarlo en una especificación estándar, puede asegurarse de que todas las partes interesadas compartan la misma visión sobre cómo funcionará una API. También facilita el intercambio de definiciones y funcionalidades reutilizables entre equipos.

Actualmente existen tres especificaciones de API comunes, cada una de las cuales admite la mayoría de los tipos de API:

OpenAPI – descripciones en JSON o YAML de todas las API web y webhooks
AsyncAPI – Descripciones en JSON o YAML de API basadas en eventos
JSON Schema – descripciones JSON de los objetos de esquema utilizados para las API

Actualmente, las API REST constituyen la mayoría de las API en producción, y la especificación OpenAPI es la forma estándar de redactar la definición de una API REST. Proporciona un contrato legible por máquina que describe cómo funciona una API determinada. La especificación OpenAPI es compatible con una amplia variedad de herramientas de gestión de API y puertas de enlace de API, incluido NGINX. El resto de este artículo se centrará en cómo puede utilizar la especificación OpenAPI para abordar algunos casos de uso importantes.

La especificación OpenAPI es un formato de código abierto para definir API en JSON o YAML. Permite incluir una amplia variedad de características de una API, como muestra el siguiente ejemplo sencillo. En este caso, una simple solicitud HTTP GET devuelve una lista de artículos de una lista de la compra ficticia.

openapi: 3.0.0info:
  version: 1.0.0
  title: Grocery List API
  description: An example API to illustrate the OpenAPI Specification

servers:
url: https://api.example.io/v1

paths:
  /list:
    get:
      description: Returns a list of stuff on your grocery list             
      responses:
        '200':
          description: Successfully returned a list
          content:
            schema:
              type: array
              items:
                type: object
                properties:
                   item_name:
                      type: string

Las definiciones que siguen la especificación OpenAPI son legibles tanto por personas como por máquinas. Esto significa que existe una única fuente de información fiable que documenta el funcionamiento de cada API, algo especialmente importante en organizaciones con numerosos equipos que desarrollan y gestionan APIs. Por supuesto, para administrar, gobernar y proteger APIs a gran escala, debes asegurarte de que el resto de las herramientas de tu plataforma de APIs —puertas de enlace de API, portales para desarrolladores y seguridad avanzada— también sean compatibles con la especificación OpenAPI.

Profundiza en cómo diseñar API REST utilizando la especificación OpenAPI en el capítulo 1 de Mastering API Architecture.

Ventajas de adoptar una especificación común para las API

Usar una especificación de API común, como la especificación OpenAPI, ofrece varias ventajas:

Interoperabilidad mejorada – Una especificación común y legible por máquina permite que distintos sistemas y clientes consuman y utilicen el contrato de la API. Esto facilita a los equipos de Operaciones de Plataforma la integración, gestión y supervisión de arquitecturas complejas.
Documentación coherente – El contrato de la API se documenta en un formato estándar que incluye los endpoints, los formatos de solicitud y respuesta, y otros detalles relevantes. Muchos sistemas pueden utilizar el contrato para generar documentación completa, lo que aporta claridad y facilita a los desarrolladores la comprensión de cómo utilizar la API.
Mejores pruebas – Las especificaciones de la API pueden utilizarse para generar y ejecutar pruebas automáticamente, lo que ayuda a garantizar que la implementación de la API se ajuste al contrato y funcione según lo previsto. Esto permite detectar problemas en una API antes de publicarla en producción.
Seguridad mejorada – Las herramientas de seguridad avanzadas pueden utilizar la especificación OpenAPI para analizar el tráfico de la API y el comportamiento de los usuarios. Pueden aplicar un modelo de seguridad positiva<.htmla> verificando que las solicitudes a la API cumplan con los métodos, endpoints y parámetros admitidos por el endpoint de la API. El tráfico que no cumple estos requisitos se bloquea de forma predeterminada, lo que reduce el número de llamadas que deben procesar sus microservicios.
Evolución más sencilla – Las especificaciones de API pueden facilitar la evolución del contrato de la API y de la propia aplicación a lo largo del tiempo, ya que proporcionan una forma clara y estandarizada de documentar y comunicar los cambios en formatos legibles tanto por máquinas como por personas. Junto con unas prácticas adecuadas de control de versiones, esto ayuda a minimizar el impacto de los cambios en los consumidores de la API y garantiza que esta siga siendo compatible con versiones anteriores.

En general, el uso de una especificación de API común puede ayudar a mejorar la interoperabilidad, la documentación, las pruebas, la seguridad y la evolución gradual de una API.

Cómo NGINX facilita el desarrollo de software basado en API

NGINX ofrece un conjunto de herramientas ligeras y nativas de la nube que facilitan la operación, supervisión, gobernanza y protección de las API a gran escala. Por ejemplo, API Connectivity Manager, que forma parte de F5 NGINX Management Suite, proporciona un único plano de gestión para las operaciones de sus API. Con esta herramienta puede configurar y gestionar puertas de enlace de API y portales para desarrolladores. Al ser una herramienta basada en el enfoque API-first, todas sus funciones son accesibles mediante una API REST, lo que facilita la automatización de CI/CD y la integración para los equipos de DevOps.

Con la especificación OpenAPI, puede utilizar los productos de NGINX para:

Publicar API en la puerta de enlace de API
Generar documentación de la API para el portal de desarrolladores
Aplique seguridad positiva para proteger los endpoints de la API

Utilice la especificación OpenAPI para publicar una API en la puerta de enlace de API y la documentación en el portal para desarrolladores, así como para configurar políticas de seguridad para el WAF mediante canalizaciones de CI/CD o la interfaz de usuario

Publicar API en la puerta de enlace de API

API Connectivity Manager utiliza la especificación OpenAPI para agilizar la publicación y la gestión de las API. Los desarrolladores pueden publicar API en la puerta de enlace de API mediante la interfaz de usuario de NGINX Management Suite o la API REST totalmente declarativa. Las API se añaden a la puerta de enlace como proxies de API, que contienen todas las configuraciones de entrada, backend y enrutamiento que la puerta de enlace necesita para dirigir las solicitudes de API entrantes al microservicio de backend. Puede utilizar la API REST para desplegar y gestionar las API como código mediante la creación de sencillos scripts de automatización de CI/CD con herramientas como Ansible.

Para obtener instrucciones completas sobre cómo usar la especificación OpenAPI para publicar una API, consulte la documentación de API Connectivity Manager.

Generar documentación de la API para el portal de desarrolladores

Mantener la documentación suele ser un quebradero de cabeza para los equipos de API. Sin embargo, la documentación desactualizada en los portales para desarrolladores también es un claro síntoma de la proliferación descontrolada de API. API Connectivity Manager utiliza la especificación OpenAPI para generar automáticamente la documentación y publicarla en el portal para desarrolladores, lo que ahorra tiempo a los desarrolladores de API y garantiza que los consumidores de API siempre puedan encontrar lo que necesitan. Puede cargar archivos de especificación OpenAPI directamente a través de la interfaz de usuario o la API REST de API Connectivity Manager.

Para obtener instrucciones completas sobre cómo publicar documentación de la API en el portal para desarrolladores, consulte la documentación de API Connectivity Manager.

Aplique seguridad positiva para proteger los endpoints de API

También puede utilizar la especificación OpenAPI para verificar que las solicitudes de API a la puerta de enlace de API de NGINX Plus se ajusten a lo que admite una API. Al aplicar seguridad positiva (un modelo de seguridad que define lo que está permitido y bloquea todo lo demás), puede evitar que las solicitudes maliciosas sondeen sus servicios de backend en busca de posibles vulnerabilidades.

En el momento de redactar este documento, no se puede usar API Connectivity Manager para configurar NGINX App Protect WAF; esta funcionalidad estará disponible más adelante en 2023. Sin embargo, puede usar Instance Manager (otro módulo de NGINX Management Suite) y la especificación OpenAPI para crear políticas personalizadas para su WAF. Para obtener más información, consulte la documentación de NGINX App Protect WAF y Instance Manager.

Obtenga más información sobre la seguridad de las API y el modelado de amenazas, así como sobre cómo aplicar la autenticación y la autorización en la puerta de enlace de API, en el capítulo 7 de Mastering API Architecture.

Resumen

Un enfoque API-first para crear microservicios y aplicaciones puede beneficiar a su organización de muchas maneras. Alinear a los equipos en torno a la especificación OpenAPI (u otra especificación de API común que sea legible tanto por personas como por máquinas) ayuda a facilitar la colaboración, la comunicación y las operaciones entre equipos.

Las aplicaciones modernas funcionan en entornos complejos y nativos de la nube. Adoptar herramientas que permitan aplicar un enfoque API-first a la gestión de las API es un paso fundamental para hacer realidad su estrategia API-first. Con NGINX, puede utilizar la especificación OpenAPI para gestionar sus API a gran escala en equipos y entornos distribuidos.

Inicie una prueba gratuita de 30 días de NGINX Management Suite, que incluye acceso a API Connectivity Manager, NGINX Plus como puerta de enlace de API y a NGINX App Protect para proteger sus API.