Apiary nos permite documentar nuestra API fácilmente y permite generarla con un estilo muy vistoso, además de tener otras funcionalidades.
Índice de contenidos
- 1. ¿Qué es Apiary?
- 2. Funciones a nuestro alcance
- 3. Una API de ejemplo
- 4. Conclusiones
- 5. Referencias
1. ¿Qué es Apiary?
Apiary es un editor para APIs que te permite usar tanto API Blueprint como Swagger, los cuales son lenguajes que nos permiten describir nuestras APIs, y gracias a ellos podemos realizar algunas tareas como mockear una API de forma sencilla y rápida.
Aunque ya las enumeraremos más detalladamente, Apiary no solo nos permite editar texto como cualquier otro editor, sino que también nos ayuda a pasar tests a nuestra API empleando Dredd. También analiza las requests con su inspector, nos permite previsualizar el documento final y compila constantemente con los últimos cambios permitiéndonos ver errores al validarlo todo (aunque puede ser molesto, por eso puede desactivarse la previsualización).
En un principio se ve bastante completo, pero ¿es fácil de usar? Parece que Apiary se ha centrado en la comodidad para el usuario, ya que la interfaz tiene la información justa y necesaria, no te abruma desde un principio como puede ocurrir con algunas herramientas con mucha opciones disponibles; mucho botón no siempre ayuda.
2. Funciones a nuestro alcance
Antes de ver las funcionalidades que nos provee hay que tener en cuenta que tiene una parte de pago.
A la hora de crear APIs puedes hacerlo como un usuario normal o como un Team o equipo. Un equipo lo forman un conjunto de usuarios y el grupo es el que tiene las APIs, no un usuario en concreto. Lamentablemente los equipos tienen una barrera que es el dinero: 99$ mensuales.
Aunque hacer un equipo no sea gratuito, podemos usarlo personalmente para diseñar nuestras propias APIs con un editor muy cómodo, además de que nos brinda un abanico de opciones para facilitarnos la tarea.
Ahora que tenemos claro qué no podemos hacer, vamos a ver lo que sí podemos hacer. Apiary nos deja a mano las siguientes posibilidades:
- Un editor que cuenta con dos estilos y varios tamaños de letra, además de una previsualización muy cómoda y una consola que permite hacer ejemplos y ver la especificación.
- Genera la documentación de forma que pueda compartirse para ver y editar entre unos pocos, ya que se encuentra limitado, para aumentar el número de invitaciones hay que pagar.
- Permite vincular la documentación con tu proyecto de GitHub.
- Permite probar el diseño sobre tu implementación real de la API.
- Tiene un inspector de llamadas sencillo de usar.
- Aporta una interfaz limpia para hacer tests con Dredd, con un serie de pasos para poderlo usar.
3. Una API de ejemplo
Crear una nueva API es tan sencillo como pulsar un botón, generando así una API de ejemplo con la que empezar.
Mediante este ejemplo se muestra cómo trabaja Apiary y cómo se vería el documento final. Cabe destacar que Apiary nos obliga a tener como mínimo una API.
Como puede verse, Apiary nos genera rápidamente una documentación bonita y limpia, con desgloses que abren la consola que es la responsable de mostrar la request en detalle.
El inspector también es interesante, ya que podemos observar todas las llamadas de ejemplo que vamos haciendo, no solo su resultado final. No escatima en detalles y nos muestra el mensaje completo.
También es interesante el apartado de tests, ya que nos permite ver los que realizamos en local, en integración continua y en post-deployment y además nos añade un pequeño tutorial para emplear Dredd, que lo usa para ejecutar los tests sobre nuestra API, mostrando dónde y por qué ha fallado, además de comparar el mensaje que espera y el que ha recibido realmente para que puedas ver el problema fácilmente.
Como puede verse, Apiary es una herramienta muy completa, y es web, con lo cual es muy cómoda de usar.
4. Conclusiones
Podemos ver que Apiary, sin tener en cuenta la barrera de pago ante equipos, es muy completo y su simplicidad sorprende, con conocimientos básicos puedes usarlo sin problemas. Con solo tener que aprender la sintaxis de API Blueprint puedes obtener resultados muy buenos.
El poder usar Dredd con unos sencillos pasos le da más puntos si cabe, además de que si queremos hacer pruebas con Drakov y Dredd es tan sencillo como copiar todo y pegarlo en un archivo que creemos para poder usarlo localmente.
En definitiva, una herramienta con muchas posibilidades y que merece la pena probar, aunque los límites de pago pueden incomodar el trabajo para algunos.
5. Referencias
- Documentación de API Blueprint.
- Tutorial de Miguel Arlandy sobre API Blueprint y Dredd.
