Desde el Clúster de Experto en Apificación de AXPE hemos definido una Estrategia de Apificación que tiene como objetivo detallar una serie de Código de Buenas Prácticas en torno al diseño de las APIs.
Dentro de nuestra serie de artículos “modelo de referencia de AXPE para la Metodología API”, detallaremos cada una de las partes de la misma. El primer artículo será Introducción y Pautas Generales, seguido de los siguientes artículos: Diseño, Gestión de Errores API y Modelo de Datos.
El objetivo principal es homogeneizar y estandarizar su estructura para:
- Simplificar el consumo tanto por equipos internos de la compañía como proveedores externos.
- Facilitar la toma de decisiones en torno al diseño.
- Acelerar los proyectos de los diferentes equipos al hablar un lenguaje común.
Antes de continuar, se debe comprender ¿Qué es una API?
Una API es una interfaz expuesta por un sistema para establecer una forma técnica y funcional de interacción con múltiples sistemas. Es un contrato y una vía de acceso que permite la interoperabilidad entre sistemas, cumpliendo las siguientes características:
- Las APIs deben tener una correcta visualización y exposición (API Portal).
- Deben estar correctamente versionadas.
- El consumo de esta debe estar manejado mediante permisos de las aplicaciones, planes de consumo y visibilidad de esta.
- Debe estar definida utilizando un estándar: OpenApi 3, RAML, etc.
- La definición del diseño debe estar desacoplada de la implementación.
- Diseño e implementación deben estar en inglés.
- La documentación de la API puede estar en inglés.
- Toda API debe tener expuesta una versión mock. Se trata de una versión de la API que se comporta de forma real, devolviendo un conjunto de datos estáticos que simula el comportamiento de la API real.
Una vez entendido el concepto de API y sus características, vamos a explicar en nuestro modelo qué pautas generales son las que hemos definido
- La primera pauta, es establecer a quién va Destinado. Normalmente va a equipos que contenga perfiles técnicos y funcionales con conocimientos a la hora de definir especificaciones APIs, que hagan uso de algún producto de API Management, Ej: Kong, Mulesoft Platform, Azure API Management, etc.
- Estructura de la Especificación: Un documento OpenAPI puede estar formado por un solo documento o dividirse en varias partes conectadas a discreción del autor. En este último caso, se utilizan palabras clave, como .Schema, Object, $ref, étc.
Se recomienda que el nombre del fichero de la especificación se llame, openapi.yaml.
Por otro lado, desde Axpe, seguimos la filosofía de “divide y vencerás”, donde apostamos por hacer estructuras pequeñas, simples y muy acotadas a algo concreto con el fin de poder reutilizarlas dentro de un mismo documento OpenAPI, o incluso desde otros documentos diferentes. - Especificación: La especificación de una API indica un conjunto de prácticas, protocolos de comunicación y estructuras que definirán el contrato. Debido a que es un estándar, nos basaremos en la especificación OpenAPI para todas las API síncronas y en las especificaciones OpenAPI y AsyncAPI para las asíncronas. La versión de OpenAPI debe ser la misma para todos las APIs, en nuestro caso siempre se hará uso de la versión 3.
- Idioma: Se establece el inglés como idioma para definir nuestras especificaciones APIs, es decir, todos los componentes necesarios desde la definición de URL, objetos, atributos hasta documentación asociada a los mismos (descripciones, ejemplos, etc). Esto es así debido a que el inglés es el idioma de mayor acogida en la comunidad global de tecnologías de la información.
- Ejemplos: se recomienda definir ejemplos a nivel del Request y Response de cada operación y sólo a este nivel. Ya que, si cualquiera de los objetos que los componen, se modificase, sólo habría que actualizar estos ejemplos.
Los ejemplos son de vital importancia de cara al correcto entendimiento del diseño de nuestra API. Si bien nosotros no lo enfocamos como algo restrictivo (must), si consideramos que deba ser algo muy recomendado (should) que debe venir bien especificado en la normativa de diseño de API.
Los ejemplos harán comprender mucho mejor cada recurso y endpoint de las API, tanto a los desarrolladores de la misma como a los desarrolladores de las aplicaciones que van a ser consumidores.
A mayores, los ejemplos nos permiten generar mocks de pruebas de las API que nuestros consumidores pueden utilizar para realizar sus pruebas unitarios de forma independiente al grado de avance de la implementación de las mismas desde el lado del backend.
- Extensión de Atributos: En los casos que se necesite un atributo personalizado y se requiera definir en la especificación deberán seguir el siguiente formato, comenzar con “X-”. Ej: X-Request-ID.
El nombre de los atributos debe estar marcado por el diccionario de datos de entidades de negocio. Dentro de una correcta metodología de diseño de API, disponibilidad un catálogo de entidades de negocio con sus atributos se hace fundamental para alinear las API con el negocio, los productos y los servicios.
Por tanto, nuestros recursos y nuestras API han de estar siempre basados en entidades del negocio de nuestra compañía.
Siempre existen atributos a nivel técnico, a nivel de control, etc. dentro de API de control y/o de sistemas. Estos atributos, que no forman parte de las API de negocio (estructuras y entidades de negocio) han de identificarse de forma clara, con el fin de representar información que no es de negocio, sino que es información de control/técnica requerida para la ejecución de los servicios solicitados.
- Estructura Objetos definidos: Es necesario definir el atributo titleen todos objetos definidos en la especificación, siendo igual al nombre del objeto definido. E objetivo es que los validadores, como Espectral puedan reconocer dicho objeto y así facilitar las posibles reglas definidas.
- Versionado: Parte fundamental es el versionado de una API, ya que a medida que evolucionan las necesidades del negocio, la API evolucionara conjuntamente. Para ello seguiremos un estilo de semántico (https://semver.org/) para versionar nuestras APIs.
El versionado de un API es responsabilidad del diseñador de las mismas, así como de su cumplimiento y del equipo de gobierno el controlar que se hace bien. Desde nuestro punto de vista, el estilo de versionado semántico es muy interesante y cubre, de forma completa, cualquier necesidad de evolución (e identificación de la misma) de las API.
A modo de conclusión, desde el Clúster de Expertos en Apificaciónde Axpe establecemos que estas pautas generales descritas son de vital importancia comprender para poder establecer los principios básicos para así entender el “modelo de referencia de AXPE para la Metodología API”.
Como aperitivo de la siguiente entrega, entraremos en detalles en las normativas y estándares necesario que se deben comprender a la hora de definir y/o diseñar una especificación, desde la normativa de tipos de código de estado a utilizar por cada verbo, como utilizar los POST con acciones (event-handlers o controllers), establecer cabeceras en cada uso, definición y partes de la URLs, modelado de recurso, HATEOS, paginación, filtros, etc.