Creación de un catálogo de API interno con Atlassian Compass
Katie Silver
RESPONSABLE PRINCIPAL DE PRODUCTOS DE ATLASSIAN
Resumen ejecutivo
Aquí va el resumen ejecutivo
Duración
Lectura de 4 minutos. Menos de 10 minutos para configurar Compass.
Público
Formas parte de un equipo de entrega de software y usas varias API. Puede resultarle útil a desarrolladores, ingenieros, etc.
Requisitos previos
- Consigue Compass: puedes probarlo gratis y solo tardarás unos minutos en empezar.
Crear un catálogo de API preciso es una tarea ardua
Durante la última década, hemos cambiado los grandes monolitos por microservicios, arquitecturas distribuidas y equipos autónomos. Esto ha conllevado ventajas tangibles, pero también ciertas repercusiones. Para garantizar el correcto funcionamiento de todos los componentes de un gran código base, se utilizaban los compiladores tipados y las pruebas. Hoy en día, los límites los marcan las API y no se puede saber con certeza si encajarán entre sí una vez implementadas.
Sabemos que los desarrolladores avanzan más rápido y los equipos lanzan mejores productos si todo el mundo está al tanto del funcionamiento de las API y de cuándo se modifican. El gran reto radica en la supervisión y el mantenimiento de esa documentación.
En lo relativo a los mapas de servicios, cada organización se encuentra en un nivel de desarrollo diferente. En algunos equipos, las conversaciones a través de Slack ayudan a fomentar la coordinación entre los productores y los consumidores de API. En otros, al crear el servicio, se documenta la forma en que funciona cada API, pero esta información nunca se actualiza. Si dispones de buenos procesos o herramientas, cada API estará documentada y los cambios que se introduzcan se comunicarán automáticamente a las otras partes interesadas.
Independientemente de la fase del trayecto en la que te encuentres, Compass, la nueva plataforma para desarrolladores de Atlassian, puede ayudarte.
Documentación de API centralizada con Compass
¿Dónde debería residir la documentación de API en el mundo de los microservicios? Solo porque creemos e implementamos nuestros servicios de manera independiente no significa que queramos que cada servicio tenga su propio sitio de documentación alojado, o bien un archivo de OpenAPI que no se sepa muy bien donde está. Los equipos quieren reunir toda esa información y que se pueda consultar sin que esto suponga un enorme esfuerzo interno a la hora de crear un registro de API.
Compass facilita la tarea de centralizar toda tu documentación de API en una hora, no en una semana ni un trimestre. Cada vez que hagas un cambio, no será necesario que subas la documentación de forma manual, tan solo tendrás que conectar tu SCM (Bitbucket, GitHub o GitLab) a Compass.
En solo unos minutos, Compass analizará todos tus repositorios en busca de archivos de OpenAPI y los publicará en tu catálogo. Todas las API de tus equipos se convertirán de inmediato en activos centralizados donde poder hacer búsquedas.
Descubrimiento e integración con una API
Imagina que un desarrollador se hace cargo de un ticket para crear un nuevo flujo de reembolsos. Sabe que necesita encontrar la API adecuada para tramitar un reembolso, pero no sabe por dónde empezar. En muchas empresas, este desarrollador se limitaría a preguntar por Slack y posiblemente esperaría unas cuantas horas a que un compañero del otro lado del mundo respondiera a sus preguntas sobre qué API usar. En equipos con Compass, todo este proceso se puede gestionar mediante el autoservicio. Los desarrolladores pueden buscar los endpoints de la API y, en solo unos segundos, encontrar directamente en Compass la información exacta que necesitan. Esto significa que el desarrollador que busca información la encontrará más rápido y que el equipo que tiene la API en cuestión experimentará menos interrupciones.
Recibe notificaciones sobre los cambios que se aplican en la API
En el mundo de los microservicios, cada servicio se implementa de forma autónoma y a veces se aplican cambios que los consumidores deben conocer. Por suerte, Compass no solo está al tanto de la documentación de tus API, sino que también sabe qué cambios experimentan a lo largo del tiempo. Cada vez que un compañero fusiona una solicitud de incorporación de cambios que deriva en una actualización de la documentación de tu API, Compass actualiza también su versión de la documentación. Por ello, la versión que ven los desarrolladores en Compass siempre corresponde a la API más reciente.
Del mismo modo, también se puede consultar el historial de cambios en la página del registro de cambios. De esta forma, podrás ver cuándo se aplicaron algunos de los cambios anteriores más importantes:
Cuando los desarrolladores tienen la documentación que necesitan, se lanza el código más rápido
En una encuesta reciente de Postman en la que participaron desarrolladores de API, el 52 % afirmó que el mayor problema al que se enfrentaban al trabajar con API era la falta de documentación. La falta de documentación ralentiza el desarrollo, aumenta la dificultad del proceso de incorporación de los nuevos ingenieros y merma la fiabilidad del software.
Si tuvieras que crear tu propio catálogo interno de API, sería un proyecto de gran envergadura, con un gran número de componentes cambiantes. Por ello, nos hemos encargado de todo ese trabajo por ti, con un centro de documentación centralizado al que podrás acceder en cuestión de minutos.
Proporciona a tu equipo la información que necesita y observa cómo agilizan los lanzamientos 🚀.