Y que nadie te habia dicho que se podia hacer.

Introducción

En Anypoint Studio tenemos una funcionalidad muy buena y práctica que nos permite importar una especificación de una API a nuestro proyecto, lo cual creará de forma automática los escuchadores (listeners), estructura de nuestros solicitudes (requests), respuestas (responses) y una gestión básica de manejo de errores. Todo esto en una forma estándar y ordenada que hace que nuestra aplicación sea fácil de entender y mantener. Y para hacer mucho mejor esta funcionalidad permite reimportar los cambios sin dañar nada existente o de nuestro desarrollo en progreso.

Lo que nos enseñan y que se puede encontrar en sin fin de tutoriales es como utilizar la funcionalidad de forma impecable con anypoint platform, pero lo que no nos dicen, o al menos no nos dan mucha documentación, es que esta funcionalidad tambien se puede utilizar practicamente de la misma forma desde nuestro equipo local sin necesidad de utilizar anypoint platform.

Hay algunas razones por las cuales se podria considerar hacerlo de esta manera:

• No se desea pagar anypoint platform.
• Aunque se este realizando el pago por Anypoint Platform se requiere alguna prueba de concepto o algún proyecto pequeño que no debe ser publicado en la plataforma, usualmente evitando llenar la plataforma con proyectos que que no llegan a madurar y solo generan confusión con los proyectos reales.
• Se tiene algun proceso alterno al de anypoint platform para hacer todo el ciclo de desarrollo.

En este tutorial vamos a ver como se puede importar una especifiación desde nuestro disco local en un proyecto completamente nuevo, luego en un proyecto que ya ha iniciado, pero que no se incluyó ninguna especificación y finalmente el caso de reimportar la especificación en un proyecto que ya tiene un import previo.

Diseñando la API

No es el objetivo de este artículo, pero para realizar el diseño de una API se pueden utilizar multiples herramientas, claro esta que tambien depende de que tipo de especificación vamos a utilizar, si OAS (Open API Spec) o RAML (Restful API Modeling Language). En estos ejemplos vamos a usar RAML y la herramienta API-Designer.

A modo de ejemplo vamos a utilizar una simple aplicación que nos va a permitir administrar contactos.

#%RAML 1.0
title: Contact Managament
baseUri: /1.0.0/
version: 1.0.0
description: API to manage contacts

types:
  contact: 
    type: object
    properties:
      id:
        type: integer
        required: false
      firstName:
        type: string
        required: false
      lastName:
        type: string
        required: true
      age:
        type: number
        required: false

/contacts:
  get:
    description: Get Contacts
    queryParameters: 
      firstName:
        type: string
        required: false
      lastName:
        type: string
        required: false
    responses: 
      200:
        body: 
          application/json:
            type: contact[]
            examples: 
              values:
              - 
                id: 1
                firstName: 'Jhon'
                lastName: 'Doe'
                age: 35
              - 
                id: 2
                firstName: 'Jane'
                lastName: 'Doe'
                age: 20

en el api-designer se ve de la siguiente manera

Importando en un Nuevo Proyecto

Con nuestra especificación inicial vamos a crear un nuevo proyecto de Mulesoft e importar nuestra API.

Creando un Proyecto Mulesoft en Anypoint Studio

En esta guía los ejemplos utilizan la interface en el idioma ingles de Anypoint Studio, sin embargo esto no debería de variar mucho en la versión español de la interface.

para crear un nuevo proyecto de Mulesoft en Anypoint Studio Selecionamos file > new > Mule Project

En la ventana que nos aparece ingresamos un nombre para nuestro proyecto, sugiero ‘ContactManagement’ para el ejemplo, luego seleccionamos la pestaña “Import RAML from Local File” y en el campo location seleccionamos la ubicación de nuestra especificación en formato RAML y finalmente presionamos el botón “finish”.

Felicidades, esto iniciara el proceso de importado de nuestro proyecto desde la especificación y al finalizar creara los correspondientes componentes en el proyecto.

Explorando los Resultados

Si todo salió correctamente tendremos un archivo llamado interface.xml en la carpeta src/main/mule

Tendremos una copia local de nuestra especificación en la carpeta src/main/resources/api

Tendremos nuestra estructura creada con todos los listeners, requests y responses que se especificaron en el RAML y adicionalmente una gestión básica de errores.

Si en estos momentos ejecutamos nuestro proyecto y accedemos a console, podremos interactuar con nuestra API

Felicidades, ahora a programar el contenido de nuestra app de mulesoft.

Importando en un Proyecto en Curso

Esta es otra situación que podria ocurrir, es decir, iniciamos un proyecto sin ninguna especificación, realizamos lo que tenemos que realizar y todo es felicidad hasta que nos piden incluir la especificación.

Es aqui donde nos encontramos que no hay una forma intuitiva de hacerlo, tratas de buscar documentación y no la hay, pero por suerte aqui te voy a explicar como lograrlo.

creemos un nuevo proyecto sin niguna especificación, y para esto vamos Selecionamos file > new > Mule Project

y en esta ventana solo seleccionamos el nombre del proyecto, en este caso lo llamaremos “ContactManagement2” y presionamos el botón “finish”

En este punto no hay forma de incluir una especifiación RAML local a nuestro proyecto, al menos no a traves de ningna opción en los menus, sin embargo si podemos hacerlo manualmente. Si recuerdan cuando desde el inicio se crea un proyecto con un RAML, se crea una copia local en la ubicación src/main/resources/api, pues si revisamos en este proyecto no vamos a encontrar nada y esto obviamente porque no utilizamos ningun RAML en la creación del proyecto

Como se imaginaran, para incluir una especificación en nuestro proyecto simplemente basta con colocar nuestra especificación en esa carpeta, luego le damos click derecho y “refresh”, con esto deberiamos de ver nuestra especificación en nuestro proyecto

Ahora si le damos click derecho sobre el archivo “interface.raml” > Mule > Generate Flows from Local REST API

Esto generá nuestra interface como si lo hubieramos importando desde el principio generando todos los listener, requests y responses con la gestión basica de errores. La unica diferencia es que seguramente ya se tiene toda una lógica implementada en otros flujos, por lo que te tocaria iniciar la conexión de lo existente con la interfaz recien importada.

Para mantener un orden y evitar trabajar doble o sin order, siempre intenta iniciar un proyecto importando la especificación desde el inicio.

Reimportando en un Proyecto en Curso

Si seguiste el ejercició anterior, la verdad es que este no presenta mucha diferencia, es decir, es tan fácil como agregar los cambios de nuestra especificación en nuestra carpeta local del proyecto en src/main/resources/api y luego le damos “Generate Flows from Local REST API”.

Realicemos un ejercicio práctico, a nuestra interface le vamos a agregar la habilidad de agregar nuevos contactos y como es buena práctica lo vamos a realizar utilizando el metodo HTTP POST.

post:
    description: Insert a contact
    body: 
      application/json:
        type: contact
    responses: 
      201:
        body: 
          application/json:
            type: string
            example: "contact created with id 3"

como se puede apreciar simplemente se pasa un object “contact” y si se registra correctamente retorna un mensaje indicando el id con el que se creo aquel contacto.

El archivo completo es el siguiente:

#%RAML 1.0
title: Contact Managament
baseUri: /1.0.0/
version: 1.0.0
description: API to manage contacts

types:
  contact: 
    type: object
    properties:
      id:
        type: integer
        required: false
      firstName:
        type: string
        required: false
      lastName:
        type: string
        required: true
      age:
        type: number
        required: false

/contacts:
  get:
    description: Get Contacts
    queryParameters: 
      firstName:
        type: string
        required: false
      lastName:
        type: string
        required: false
    responses: 
      200:
        body: 
          application/json:
            type: contact[]
            examples: 
              values:
              - 
                id: 1
                firstName: 'Jhon'
                lastName: 'Doe'
                age: 35
              - 
                id: 2
                firstName: 'Jane'
                lastName: 'Doe'
                age: 20 
  post:
    description: Insert a contact
    body: 
      application/json:
        type: contact
    responses: 
      201:
        body: 
          application/json:
            type: string
            example: "contact created with id 3"

Seguimos los mismo pasos como en el caso anterior, es decir, copiamos este archivo en la carpeta src/main/resources/api, pero como ya el archivo existe, lo reemplazamos, luego le damos click derecho y “refresh” y finalmente click derecho sobre el archivo “interface.raml” > Mule > Generate Flows from Local REST API. Con esto ya tenemos nuestra importación completa y veremos un nuevo componente para nuestro metodo POST.

El reimportar funciona exactamente igual como si lo hubieramos reimportado desde Anypoint Platform. Espero les sea util.

Conclusiones

• Es importante mantener nuestro proyecto alineado con nuestra especificación y aunque no se este realizando el pago de Anypoint Platform, esto no es excusa para no realizarlo.
• No existe mucha documentación para manejar este escenario de importar y reimportar una especificación de forma local, pero como se demuestra en esta guía se puede realizar.

Muchas gracias por leer. Compartir es gratis.