Directrices generales en el modelo de referencia para la metodología API

Directrices Generales en el Modelo de Referencia para la Metodología de API

En el Cluster de Expertise en API de AXPE, hemos definido una Estrategia de API con el objetivo de establecer un conjunto de Mejores Prácticas para el diseño de APIs.

Como parte de nuestra serie de artículos “Modelo de Referencia AXPE para la Metodología API”, detallaremos cada aspecto de esta metodología. El primer artículo cubrirá la Introducción y Directrices Generales, seguido de temas como Diseño, Gestión de Errores en API y Modelado de Datos.

Objetivos

El objetivo principal de esta metodología es estandarizar y homogeneizar las estructuras de las API para:

Simplificar el consumo de API tanto para equipos internos como para proveedores externos.
Facilitar la toma de decisiones en el diseño de API.
Acelerar los proyectos de desarrollo garantizando un lenguaje común entre equipos.

¿Qué es una API?

Una API (Interfaz de Programación de Aplicaciones) es una interfaz expuesta por un sistema para establecer un medio de interacción técnico y funcional con múltiples sistemas. Actúa como un contrato y una puerta de acceso que permite la interoperabilidad entre sistemas, con las siguientes características clave:

Las APIs deben estar visibilizadas y expuestas correctamente a través de un Portal de API.
Deben estar versionadas correctamente.
El consumo de la API debe ser gestionado mediante permisos de aplicaciones, planes de consumo y configuraciones de visibilidad.
Las APIs deben seguir un estándar reconocido (por ejemplo, OpenAPI 3, RAML, etc.).
El diseño e implementación deben estar desacoplados.
El diseño e implementación de las API deben estar en inglés.
La documentación de la API también puede estar en inglés.
Cada API debe tener una versión mock, un modelo de respuesta estático que simula el comportamiento real de la API.

Directrices Generales

1. Público Objetivo

Esta metodología está diseñada para equipos técnicos y funcionales con experiencia en especificación de API, especialmente aquellos que utilizan herramientas de Gestión de API como Kong, Mulesoft Platform o Azure API Management.

2. Estructura de Especificación

Un documento OpenAPI puede estructurarse como un archivo único o dividirse en múltiples partes interconectadas utilizando palabras clave como .Schema, Object, $ref, etc.

Recomendamos nombrar el archivo de especificación como openapi.yaml.

En AXPE, seguimos la filosofía “divide y vencerás”, favoreciendo estructuras pequeñas, modulares y altamente específicas que puedan reutilizarse dentro de un único documento OpenAPI o en múltiples documentos.

3. Especificación de API

Las especificaciones de API definen prácticas, protocolos de comunicación y estructuras que establecen el contrato.

Las APIs síncronas deben seguir la especificación OpenAPI.
Las APIs asíncronas deben usar tanto OpenAPI como AsyncAPI.
La versión de OpenAPI debe ser consistente en todas las APIs (siempre versión 3).

4. Idioma

El inglés es el idioma obligatorio para la definición de especificaciones de API.
Esto aplica a URLs, objetos, atributos y documentación (descripciones, ejemplos, etc.).
La razón es que el inglés es el idioma predominante en la comunidad global de TI.

5. Ejemplos

Los ejemplos deben definirse a nivel de solicitud y respuesta para cada operación.

Estos cumplen múltiples propósitos:

Mejorar la comprensión del diseño de la API tanto para desarrolladores como para consumidores de API.
Permitir la creación de pruebas mock de API, facilitando a los consumidores la realización de pruebas unitarias independientes del avance del desarrollo backend.

Aunque no es obligatorio (must), recomendamos encarecidamente (should) proporcionar ejemplos claros y bien documentados como parte del estándar de diseño de API.

6. Extensión de Atributos

Cuando se necesiten definir atributos personalizados, deben seguir el formato “X-“ (por ejemplo, X-Request-ID).

La nomenclatura de atributos debe alinearse con el diccionario de datos de la entidad de negocio. Una API bien estructurada debe hacer referencia a un catálogo de entidades de negocio y sus atributos para garantizar la alineación con procesos, productos y servicios de negocio.

Las APIs también pueden contener atributos técnicos o de control que no forman parte de entidades de negocio. Estos deben estar claramente identificados para diferenciarlos de la información relacionada con el negocio.

7. Estructura de Objetos

Cada objeto definido debe incluir un atributo de título, cuyo valor coincida con el nombre del objeto.

Esto permite que las herramientas de validación (por ejemplo, Spectral) reconozcan y apliquen reglas predefinidas.

8. Versionado

El versionado de API es crítico a medida que evolucionan las necesidades del negocio.

Seguimos el versionado semántico (semver.org) para gestionar la evolución de las API.

Los diseñadores de API son responsables de definir y mantener las versiones.
El equipo de gobernanza garantiza el control de versiones adecuado en todas las API.

El versionado semántico proporciona cobertura completa para rastrear la evolución de la API y garantizar la compatibilidad.

Conclusión

En el Cluster de Expertise en API de AXPE, consideramos que estas directrices generales son esenciales para establecer los principios fundamentales de nuestro Modelo de Referencia para la Metodología API.

En nuestro próximo artículo, abordaremos estándares y mejores prácticas de diseño de API, incluyendo: