Llegando a la estación: La evolución de nuestra plataforma de documentación de API

Hace tres años nació nuestra plataforma de documentación. Poco sabíamos del impacto que algunas de las decisiones de diseño que tomamos entonces iban a tener ahora. Por ejemplo, optamos por construir una aplicación web de código abierto utilizando Ruby on Rails en lugar de generadores de sitios estáticos para archivos markdown, por ejemplo, Jekyll, Middleman, etc.

La historia hasta ahora

Un framework web, como Rails, era la elección perfecta porque no hacen suposiciones sobre lo que se construirá con ellos, lo que te da la flexibilidad de decir que sí a todo.

Hace tres años, no sabíamos cuál sería en última instancia el alcance de nuestro proyecto como empresa de API en rápida evolución. Es difícil imaginar hasta qué punto ha crecido nuestra plataforma de documentación, y es aún más difícil imaginar en qué podría convertirse en el futuro.

En la actualidad, las herramientas de la plataforma han aumentado considerablemente. Desde la corrección ortográfica automatizada y la internacionalización hasta la comprobación de la validez y el estilo de las especificaciones de la API, y la lista sigue creciendo.

Desde su creación, la plataforma ha impulsado Desarrollador de API de Vonage. Vonage API Developer comenzó su vida como Nexmo Developer y, en los años transcurridos desde su creación, se ha convertido en parte de Vonage, el proveedor de comunicaciones unificadas en la nube líder a nivel mundial. Como resultado, las demandas y expectativas de la plataforma han crecido de forma exponencial.

Ese no fue el final de la historia de la evolución de la plataforma.

La historia continúa...

Hace seis meses, otro equipo de productos de la empresa se puso en contacto con nosotros porque la herramienta que estaban usando para su sitio de documentación había llegado al final de su vida útil. Estaban entusiasmados con la transición a una copia simple de la plataforma Vonage API Developer, pero desafortunadamente, no estaba lista para que la usaran. No sólo el código de la plataforma y la documentación de Vonage API Developer vivían en el mismo repositorio, sino que además, algunas de las páginas y funciones no estaban creadas para admitir otras modalidades de contenido que eran exclusivas de esa línea de productos.

La creciente complejidad de las necesidades de herramientas impuestas a una única aplicación Rails monolítica, junto con un mayor interés en la adopción de la plataforma por parte de varias líneas de productos en Vonage, nos llevó a buscar una alternativa mejor.

Así fue como llegamos a la Estación.

¿Qué es la estación?

Durante los últimos meses, hemos separado la prosa del código de la plataforma. La hemos refactorizado para convertirla en una plataforma agnóstica en cuanto a contenidos que admita una plétora de formas y soportes de contenido y potencie a otros equipos de toda la empresa.

Station es una herramienta de plataforma. Mediante la definición de unos pocos archivos de configuración y el establecimiento de la ruta a donde vive su contenido, un sitio web puede ser instanciado con un comando desde el terminal.

Está diseñado para ofrecer lo siguiente desde el primer momento:

• Una solución para crear rápidamente sitios web de contenido textual

• La posibilidad de que todo el mundo, independientemente de sus conocimientos de programación, pueda aportar contenidos de forma ágil.

• Altamente personalizable para satisfacer las necesidades de cada sitio mediante un conjunto de archivos de configuración.

En esencia, Station es una aplicación Ruby on Rails (y Webpack) altamente adaptada y empaquetada en una gema Ruby, un paquete de software reutilizable en el lenguaje de programación Ruby. Para el desarrollador Rails experimentado, le resultará familiar. Para una persona no familiarizada con Rails, será innecesario aprender los matices del framework para ejecutar o contribuir con contenido a un sitio impulsado por Station.

¿Qué hace la estación?

Una instalación de Station admite la mayoría de las cosas que cabría esperar de un sitio de contenidos desde el primer momento: representación de contenidos ricos en medios y archivos de especificación OpenAPI, tutoriales paso a paso, páginas web creadas a medida, casos de uso, posibilidad de proporcionar comentarios, búsqueda de contenidos, y la lista continúa.

No sólo el contenido, sino la mayoría de las partes del sitio pueden personalizarse con archivos de configuración. El siguiente fragmento corresponde al archivo de configuración de la cabecera y el pie del sitio.

Así es como se muestran en la página.

¿Y ahora qué?

Aunque nos alegramos de haber construido una plataforma sólida que admite cualquier sitio de contenidos y que actualmente alimenta el sitio de documentación de dos de nuestros equipos, aún no está totalmente disponible para que la utilice todo el mundo.

A pesar de que es de código abierto, la gema está siendo liberada utilizando el registro de paquetes de Github, y las versiones no están disponibles al público todavía. Sin embargo, tenemos previsto lanzar una versión pública v1.0 en breve, que estará disponible para todo el mundo a través de Rubygems.

En próximas entradas, hablaremos de algunas de las herramientas mencionadas anteriormente, que hemos creado para mantener nuestra documentación y especificaciones de API abierta de primera categoría.