APIs REST documentadas y probadas con API Blueprint y Dredd

0
11664

En este tutorial intentaremos explicar cómo documentar nuestras APIs REST con la ayuda de API Blueprint y cómo probar que el servicio de backend cumple con el contrato de manera automática gracias a Dredd.

0. Índice de contenidos.


1. Introducción

Tener una buena documentación actualizada de nuestras APIs es fundamental para facilitar la integración por parte de nuestros potenciales consumidores. En servicios web basados en SOAP tenemos la opción de WSDL para documentar nuestros contratos técnicos, pero en REST no parece que se haya impuesto ningún estilo, al menos de momento…

En este tutorial intentaremos explicar cómo documentar nuestras APIs REST con la ayuda de API Blueprint y cómo probar que el servicio de backend cumple con el contrato de manera automática gracias a Dredd.

Dredd


2. Entorno.

El tutorial está escrito usando el siguiente entorno:

  • Hardware: Portátil MacBook Pro Retina 15′ (2.2 Ghz Intel Core I7, 16GB DDR3).
  • Sistema Operativo: Mac OS Yosemite 10.10
  • Entorno de desarrollo: NetBeans IDE 8.0.2
  • Node Package Manager (npm) v2.10.0
  • Dredd v0.6.0
  • JDK 1.7 +
  • Apache Maven 3.1.1


3. La importancia de documentar las APIs.

Nuestra API es el componente que define la forma en la que los clientes deben interactuar con el servicio, las capacidades que éste expone y los tipos de datos que maneja.

Tener bien documentada la API de un servicio es fundamental, sobre todo si la vamos a exponer al exterior para que sea consumida por una gran variedad de consumidores. Por supuesto, cuando se expone de manera interna (ej. Intranet corporativa) también es muy importante una buena documentación de este contrato técnico.

Un API bien documentada nos asegura que los futuros consumidores podrán interactuar con nuestro servicio de backend con relativa facilidad. La documentación del API debe ser clara, concisa y, sobre todo, sencilla de entender por humanos. Si nuestra documentación del API es excesivamente extensa o compleja, cabe la posibilidad de que al equipo de desarrollo del servicio le dé pereza actualizar la documentación y no se corresponda con el servicio de backend.

Desde el punto de vista del diseño de servicios es fundamental seguir el enfoque Contract First con el que diseñamos primero el contrato de nuestro servicio (nuestra API) y posteriormente implementamos la lógica de backend que cumple con dicho contrato. Con esto respetamos fundamentalmente dos principios de diseño como son el de bajo acoplamiento (entre contrato e implementación) y el de abstracción del servicio.

Si contamos con servicios web (los clásicos que suelen intercambiar mensajes SOAP) no tenemos demasiado problema a la hora de documentar nuestra API ya que contamos con el lenguaje WSDL. Pero, ¿qué ocurre en el caso de contar con servicios REST?.

Con REST tenemos múltiples alternativas para documentar nuestra API aunque es cierto que parece que no hay ninguna que se imponga claramente, desde WSDL 2.0 o WADL, pasando un documento corporativo, una web (html) o incluso alguna herramienta tipo Swagger, etc…


4. Documentando el API con API Blueprint.

API Blueprint es un lenguaje basado en Markdown, muy fácil de entender por humanos y con el que podemos documentar de una manera muy sencilla nuestras APIs.

Aunque existen diferentes variantes, podríamos decir que un documento de un API escrito con API Blueprint se divide, fundamentalmente, en dos secciones:

  • API: sección relativa a la documentación general del API. Se representa con #
  • Recursos: sección relativa a la documentación de cada uno de los recursos que conforman el API. Se representa con ##. Se divide en diferentes sub-secciones:
    • Modelo: describimos los datos que conforman el recurso o entidad además de las posibles cabeceras de la petición.
    • Accion: Verbos HTTP que acepta el recurso. A su vez se divide en diferentes secciones donde las más importantes son las peticiones y respuestas.

Aquí podéis encontrar la documentación completa del lenguaje API Blueprint

En un primer momento puede parecer algo complejo pero se tarda muy poco en pillarle el truco. Es realmente sencillo 🙂

Este sería un pequeño ejemplo de documentación de un recurso «Order» representado como un objeto con atributos: id, price, vouncher y status. Dicho recurso acepta peticiones GET y ante una petición utilizando dicho verbo y negociación de tipo de contenido a JSON, se espera una respuesta con código 200 y una representación JSON del objeto «Order».

## Order [/api/orders/{id}]

+ Parameters
    + id : 999992_bd84fe278c6152c821a80ee6038effe6 (string)

+ Attributes (object)
    + id: bd84fe278c6152c821a80ee6038effe6 (string)
    + price: 2.77 (number)
    + vouncher: ACR0347Z (string) 
    + status: 1 (number) - Order status. It must be 1 (CREATED), 2 (FINISHED) or 3 (CANCELED)


### Get existing order [GET]
+ Request
    
    + Headers
        
            Accept: application/json

+ Response 200 (application/json;charset=UTF-8) 
    
    + Attributes(Order)

Y visualmente, representado por un intérprete de Markdown, sería algo como:

ApiBlueprint


4.1. ¿Por qué usar API Blueprint?.

Llegados a este punto tampoco parece que tengamos ningún motivo especial para utilizar API Blueprint. Lo que, bajo mi punto de vista, hace realmente interesante a este lenguaje basado en Markdown es el conjunto de herramientas que surgen alrededor de API Blueprint. En concreto destacaremos dos:

  • Drakov: una herramienta para levantar un servidor con un «servicio de Mocks» basado en la documentación de nuestra API. Una excelente opción para tener un servicio corriendo aceptando peticiones y devolviendo respuestas únicamente con nuestra documentación. Todavía tiene que madurar un poco pero ya empieza a tener muy buena pinta.
  • Dredd: Herramienta para testear nuestro servicio de backend en base a la documentación del API. Esta opción es excelente para comprobar que nuestra documentación está constantemente actualizada y que el servicio de backend se comporta en base a lo pactado en el contrato (documento). Hablaremos de Dredd en el siguiente punto.

Drakov

Ejemplo de servicio Mock creado a partir de la documentación con Drakov.


5. Probando el servicio a través de la documentación del API con Dredd.

Veamos cómo podemos probar nuestro servicio de backend en base a la documentación de su API.

Lo primero que haremos será instalar Dredd en nuestro equipo. Podemos hacerlo de una forma muy sencilla haciendo uso del gestor de paquetes de node (npm). Para ello, asegurándonos de tener los permisos necesarios para una instalación global del paquete, ejecutamos el siguiente comando en nuestro terminal.

npm install -g dredd

Una vez tenemos Dredd instalado globalmente en nuestro sistema, arrancamos nuestro servicio. Nosotros probaremos con el ejemplo del anterior tutorial.

Para ponerlo en funcionamiento, nos descargamos el código fuente y ejecutamos estos dos comandos:

mvn clean install
mvn tomcat7:run

Si todo salió correctamente, ya deberíamos tener nuestro servicio corriendo en http://localhost:8080/rest-idempotency.

Por último lanzamos Dredd, para que ejecute los tests de integración que comprobarán que nuestra documentación está actualizada con respecto al servicio.

Lanzamos el siguiente comando:

dredd $DOCUMENTO_API $URL_BASE_SERVICIO

Donde:

  • $DOCUMENTO_API: es la ruta al documento de nuestra API, puede ser una URL o una ruta del sistema de ficheros del equipo local. En nuestro caso utilizaremos la URL http://localhost:8080/rest-idempotency/API_DOCUMENTATION.md
  • $URL_BASE_SERVICIO: URL de donde parte nuestro servicio, a partir de dicha URL «vivirán» los recursos del API.

Lanzamos el comando:

dredd http://localhost:8080/rest-idempotency/API_DOCUMENTATION.md http://localhost:8080/rest-idempotency

Y vemos que todo funciona correctamente 🙂

DreddOutput


5.1. ¿Cómo funciona?.

Lo que hace Dredd es evaluar las acciones que se pueden realizar sobre los recursos (verbos HTTP) y, en base a las peticiones/repuestas definidas para cada acción (con API Blueprint se pueden definir tantas peticiones/respuesta como se quieran por acción) realizará dichas peticiones del mismo modo en que se reflejan en el documento. Podríamos decir que una acción sobre un recurso es un escenario y cada petición/respuesta es un caso de uso.

Dredd se basa en otra herramienta llamada Gavel para realizar las validaciones de las respuestas en base a las peticiones que realiza al API. Gavel cuenta con varios grupos de validadores para evaluar las cabeceras de petición/respuesta, códigos de retorno y el cuerpo de la petición (por desgracia, a fecha de publicación de este tutorial, solo entiende texto plano y JSON). Aquí se puede ver un ejemplo de cómo Gavel valida un objeto JSON.


6. Referencias.


7. Conclusiones.

En este tutorial hemos visto la importancia de contar con un API REST bien documentada y actualizada para facilitar la vida a nuestros consumidores tanto si lo hacen de manera externa (Internet) o interna (Intranet).

API Blueprint es una buena opción para documentar de una manera muy sencilla nuestras APIs pero lo que realmente lo hace especial es el conjunto de herramientas que giran a su alrededor. De entre ellas podríamos destacar Dredd una excelente opción para generar tests de integración de manera automática en base a nuestra documentación y facilitar nuestro proceso de documentation-driven development.

Cualquier duda en la sección de comentarios.

Espero que este tutorial os haya sido de ayuda. Un saludo.

Miguel Arlandy

marlandy@autentia.com

Twitter: @m_arlandy

DEJA UNA RESPUESTA

Por favor ingrese su comentario!

He leído y acepto la política de privacidad

Por favor ingrese su nombre aquí

Información básica acerca de la protección de datos

  • Responsable:
  • Finalidad:
  • Legitimación:
  • Destinatarios:
  • Derechos:
  • Más información: Puedes ampliar información acerca de la protección de datos en el siguiente enlace:política de privacidad