Diseñando productos de APIs

Ahora vamos a dar nuestra perspectiva de como modelar APIs. La solución que hemos desarrollado y puesto en práctica utiliza los lenguajes de modelado de ArchiMate y UML. En nuestra propuesta integramos diferentes puntos de vista para tener una visualización global, es decir: la definición de negocio que describe el por qué y para qué de las APIs, la definición de la aplicación que describe las dependencias y la orquestación de servicios.

Descripción del caso de estudio

Supongamos que tenemos un zoológico que necesita exponer dos tipos de productos de APIs:

1. Un tipo de producto de API la cual debe ser totalmente informativa, es decir, debe permitir listar animales junto con sus características, tales como: nombre, especie, forma de vida y los programas de conservación en los que están inscritos.
2. El segundo tipo de producto de API permite al zoológico mejorar el acceso a sus servicios, como: acceder al listado de animales, ubicarse geográficamente en un mapa de animales del zoológico,  acceder la de venta de tickets, etc.

Asumiremos que el zoológico cuenta con cuatro aplicaciones internas que le permiten gestionar: el inventario de animales, los cuidados específicos por animal, la ubicación geográfica dentro del zoológico y, finalmente, los programas de investigación en curso.

Propuesta de solución

Nuestra propuesta comprende cuatro tipos de diagramas cada  uno con un propósito bien definido:

• Punto de vista de producto (ArchiMate Product Viewpoint). 
  • Propósito: Describir el valor de negocio que ofrece una serie de funcionalidades agrupadas en uno o varios productos ofrecidos a un cliente final. Esta propuesta describe el valor de mercado que significa exponer una serie de funcionalidades puntuales via API.
• Punto de vista de cooperación de aplicaciones (Archimate Application Cooperation Viewpoint):
  • Propósito: Describir como se relacionan dos o más piezas de software y cómo colaboran entre si para ejecutar una funcionalidad. En esta propuesta se utiliza este diagrama en dos niveles. El primer nivel, describe las dependencias a aplicaciones de un API. El segundo nivel, describe por cada operación de API, las llamadas a los servicios expuestos por las dependencias descritas en el primer nivel.
• Diagrama de clases de UML (UML Class Diagram).
  • Propósito: Este diagrama permite describir una serie de clases, sus atributos, sus operaciones y sus relaciones. En esta propuesta, se utiliza para describir el mapa de recursos de un API para obtener las rutas REST; de esta manera, se asegura que las rutas de las operaciones son consistentes.
• Diagrama de secuencia de UML (UML Sequence Diagram).
  • Propósito: Este diagrama permite describir una secuencia de llamadas a servicios/operaciones en una línea de tiempo. En esta propuesta, se utiliza para describir la secuencia ordenada y detallada de llamadas a servicios y sus respuestas que orquesta una operación de un API que resuelve una determinada funcionalidad.

Implementación

Una vez, que hemos introducido los diagramas y sus propósitos, vamos a describir como se ha puesto en marcha la solución diagrama a diagrama.

Punto de vista de producto

Se ha mencionado en la descripción del ejemplo que son necesarios dos tipos de productos de APIs, cada producto tiene una razón por la que es importante y de valor al negocio (en este ejemplo el negocio es el zoológico).  Entonces, el punto de vista de producto, descrito en la siguiente figura, muestra en la parte superior los valores (ArchiMate Values) y en la parte inferior los productos (ArchiMate Products) para nuestro ejemplo.

El producto principal se denomina “EAMinds Zoo” y representa al conjunto de funcionalidades que el zoológico necesita ofrecer al público. Los productos contenidos dentro de “EAMinds Zoo” representan funcionalidades que se distinguen por el tipo de servicios que ofrecen, por lo tanto, tanto el producto “Informational product” como el producto “Zoo services product” están asociados a los valores de negocio descritos en la parte superior.

Ahora que hemos descrito los productos y los valores, necesitamos describir las funcionalidades intrínsecas asociadas. De esta manera, ampliamos el modelo de producto y, como se ve en la siguiente figura, a cada producto le corresponden uno o varios servicios de negocio (ArchiMate Business Services) que representan las funcionalidades expuestas representadas como funciones de negocio (ArchiMate Business Function). El servicio de negocio “Provide caring animal information” expone un conjunto de funcionalidades para gestionar la información de los programas de conservación y del inventario de animales. Por otro lado, el servicio de negocio “Handle zoo services” expone las funcionalidades de: geolocalización de los animales y control de inventario de los animales en exposición entre otros.

Hasta este momento hemos descrito el negocio que envuelve los dos productos de APIs, es decir, desde su valor para el negocio hasta el detalle de las funcionalidades que necesitan exponer. En este contexto, ahora se describen las APIs que resuelven las funcionalidades descritas en el modelo de producto utilizando servicios de aplicación (ArchiMate Application Services). Cada servicio de aplicación sirve o es usado por una o más funciones de negocio como se ve en la siguiente figura:

Se puede observar que los dos productos de APIs de esta solución, se han resuelto con cuatro APIs distintas: “/conservation_programs”, “/animals”, “/zoo_services” y “/zoo_geolocation”.

Punto de vista de cooperación de aplicaciones (Primer nivel)

En el modelo que sigue se pueden ver las dependencias del API “/animals”.  Como se dijo anteriormente, el API es la interacción de varias funcionalidades, cada funcionalidad es el resultado de interactuar con una o varias aplicaciones (vea en la figura siguiente el cuadro de dependencias). Las aplicaciones se representan con componentes (ArchiMate Application Component) y los componentes que colaboran entre si se agregan a un objeto de colaboración de aplicaciones (ArchiMate Application Colaboration) . Las colaboraciones toman el nombre del propósito por el que se agrupan los componentes, en el ejemplo: “Generic animal management” y “Specific animal management”. Ambas colaboraciones son asignadas a una interacción de aplicaciones (ArchiMate Application Interaction) denominada “Animals API”, esta interación representa todas las funcionalidades expuestas por el API.

Punto de vista de cooperación de aplicaciones (Segundo nivel)

En el segundo nivel, se describe un nivel adicional de detalle respecto del primer nivel. En este modelo se especifican, por un lado, todas las operaciones que expone una API, y por otro lado se describe, por cada operación, las dependencias a los servicios expuestos por los componentes descritos en el modelo del primer nivel. En la figura siguiente, se puede ver como “Animals API” agrupa dos interacciones, cada una de ellas representa una operación del API, en este caso, “Get animals inventory” y “Get animal status”. Además, se amplia la sección de dependencias agregando (en la parte superior de la figura) los servicios de aplicación que son usados por cada interacción de “Animals API” y, en la parte inferior, los objetos de datos (Data objects) asociados a sus componentes y que son relevantes para para las operaciones del API.

Diagrama de Clases UML

Para acceder a una API se necesita la definición de las rutas o paths que nos permite acceder a las distintas operaciones del API, dichas rutas se conforman utilizando Recursos. Los recursos son los conceptos que intervienen en una funcionalidad expuesta por un API, y como tal, no se describen como acciones sino como sujetos, es decir, que un recurso no puede ser “ObtenerCaracteristicasAnimal”, sino “Caracteristicas”. Un Diagrama de Clases UML permite describir los recursos y las relaciones entre ellos de manera que al combinarlas, se obtienen las distintas operaciones que expone el API. Los conceptos que corresponden a los recursos se describen con clases (Clases UML) y en plural, las asociaciones entre los recursos forman las rutas a las que luego se les asignan operaciones. Existen varias propuestas para este diagrama que utilizan RestUML. En esta propuesta se utiliza el UML clásico para diseñar las rutas.

En el siguiente diagrama, se utiliza una interfaz para representar el inicio de la ruta a la que denominaremos con el nombre del api “API Animals”. La relación entre la interfaz y el primer recurso describe el inicio de la ruta, en este caso /animals (y por lo tanto el nombre del API), de la misma manera, colocamos el nombre de la ruta a las relaciones entre recursos, por ejemplo, para animals y characteristics la relación se denomina /charasteristics/, por lo tanto, si queremos obtener las características de un animal la ruta REST es /animals/characteristics/, se debe tomar en cuenta la direccion de la flecha en la relación.

Si se necesita especificar operaciones a nivel de un elemento de recurso, este elemento también se describe con una clase, y la ruta entre el recurso y el elemento se describe con una variable entre llaves como  /{animal_code}, la variable seleccionada debe permitir seleccionar un solo elemento del recurso (códigos, identificadores, llaves únicas, etc)

Si se tienen varias maneras de llamar a un recurso, la relación entre recursos debe incluir el nombre de un atributo, de la siguiente manera /characteristics/specie_type/{specie_type}, de esta manera se pueden incluir tantas relaciones paralelas entre los recursos como tipos de filtros para acceder al recurso se tenga.

La figura también muestra los distintos tipos de operaciones que contiene cada recurso (GET,  PUT, PATCH, POST, DELETE) además de una descripción informativa, sólo se describen las operaciones que están implementadas por el API (Mas información de REST aqui).

Como ejemplo se describe algunas de las rutas que se pueden obtener con el modelo:

Tipo de ruta	Ruta	Descripción
GET:/animals/	GET:/animals/	Obtiene una lista de registro de animales
GET:/animals/{animal_code}/	GET:/animals/{1234}/	Obtiene los datos del animal con código 1234.
POST:/animals/{animal_code}/	POST:/animals/{1235}/	Crea el animal con código 1235.
GET:/animals/characteristics/specie_type/{specie_type}/	GET:/animals/characteristics/specie_type/{PantheraLeo}/	Obtiene las caracteristicas de la especie “Panthera Leo”.

Diagrama de Secuencias UML

Como se dijo anteriormente, se utiliza un diagrama de secuencia para describir la secuencia de llamadas a los servicios de las aplicaciones y sus respuestas por cada una de las operaciones de la API. En la figura siguiente, se pueden ver las líneas de tiempo (Lifeline) que de izquierda a derecha se corresponden con: La interfaz con el nombre de la API, el recurso que resuelve la operación, una línea de tiempo por cada componente que colabora en la funcionalidad expuesta por la operación.

Las llamadas entre líneas de tiempo corresponden a los nombres de servicios que se invocan por cada componente, y las respuestas contienen la información que retorna de cada componente al ejecutar el servicio. Se puede especificar el momento en el que se retornan las diferentes respuestas (HTTP ###)(Mas información de REST aqui)..

Relación con otras APIs

Hasta este momento, hemos descrito solo un API y sus operaciones, pero si se tienen más APIs dentro de una misma solución, se puede ver como se reutilizaran los servicios y los componentes, de manera que luego se pueda hacer un correcto análisis de dependencias.

En este ejemplo, se puede ver como el API de “/zoo_geolocation”, tiene dos operaciones, donde “Get animal location” llama al servicio de “Get Animal Information” del componente “Animal inventory management” que también fue llamado por el API de /animals.

NOTA: En este ejemplo también se puede ver la llamada a servicios externos, como los servicios de geolocalización de Google®.

Análisis

Ahora vamos a hacer un análisis de dependencias. Como se ve en la figura siguiente de izquierda a derecha, el componente de “Animal inventory management” realiza un servicio de “Get animal information” que sirve a dos operaciones del API /zoo_geolocation y a una operación del API /animals. Luego, cada API sirve a una funcionalidad de negocio, “Handle zoo services” y “Caring animals inventory” respectivamente. Finalmente, ambas funcionalidades forman parte del segundo producto del ejemplo denominado “Zoo services product”.

Como esté análisis transversal se podrían hacer muchos más, siempre que se siga el patrón adecuadamente para garantizar la integridad de los modelos.

Conclusiones

En esta entrada hemos desarrollado nuestra propuesta para diseñar productos de API, que describe la funcionalidad desde el Dominio de Negocio, hasta el diseño de software en el Dominio de Aplicación. Esto implica, el diseño de cada una de las operaciones de las APIs, un mapa de dependencias del API, entender por qué y cómo se agregan las APIs a una serie de funcionalidades expuestas por un producto y el valor para el negocio de toda la solución.

Con el caso de estudio presentado, mostramos que tenemos todos los elementos de una solución trazados entre sí. Dos productos de APIs que se ha resuelto con cuatro APIs distintas, que internamente comparten dependencias.