[Guía] Control de versiones de tus API con Postman

Mantener revisiones de API consistentes y bien documentadas es crucial para un desarrollo de API eficiente. Sin embargo, gestionar numerosas versiones y colaborar eficazmente en los cambios dentro de un equipo puede ser una tarea compleja.

Esta guía explora las funcionalidades del sistema de control de versiones integrado de Postman, lo que te permite gestionar eficazmente las versiones de la API, agilizar la colaboración y mantener un registro de auditoría claro de las modificaciones. Al aprovechar estas funciones, puedes garantizar un flujo de trabajo de desarrollo de API más organizado y eficiente.

¿Qué es Postman?

Postman actúa como un centro central para el desarrollo de API, agilizando el proceso para los programadores. Su conjunto completo de funciones abarca capacidades de diseño, pruebas y documentación. Esta consolidación de funcionalidades ha consolidado la posición de Postman como una herramienta preferida para los desarrolladores que abordan una amplia gama de proyectos relacionados con la API.

¿Qué es el control de versiones de Postman?

El control de versiones de Postman te permite a ti y a un equipo crear y modificar una API de forma colaborativa. El control de versiones se especializa en la gestión de:

Colecciones de API: Las colecciones definen tus solicitudes de API, que incluyen URL, parámetros, encabezados y contenido del cuerpo.

Entornos de API: Las variables de entorno de la API se almacenan dentro del control de versiones de Postman para ser utilizadas dentro de tus colecciones. Esto permite a los usuarios cambiar fácilmente entre entornos de desarrollo, prueba y producción.

Mocks de API: Los mocks de API simulan la respuesta del servidor para los endpoints de la API, lo que los hace útiles para fines de prueba.

Funcionalidades del control de versiones de Postman

El control de versiones de Postman ofrece una variedad de funciones para que los desarrolladores maximicen los procesos de desarrollo de la API, tales como:

Seguimiento de cambios

• Mantén un historial claro de las modificaciones de tus colecciones, entornos y mocks.
• Identifica quién realizó cambios específicos y señala la marca de tiempo exacta para mejorar la responsabilidad y la colaboración.

Forking y Merging

• Inspirado en los flujos de trabajo de Git, Postman te permite crear una copia (fork) de un elemento (colección, entorno, mock) para el trabajo independiente.
• Una vez que se completan las ediciones, fusiona fácilmente tus cambios de nuevo en la versión principal, agilizando la colaboración e integrando las contribuciones individuales.

Pull Requests

• Fomenta el desarrollo transparente permitiendo a los miembros del equipo revisar los cambios propuestos antes de fusionarlos en la versión principal.
• Este proceso colaborativo ayuda a identificar y abordar posibles conflictos antes de que interrumpan el flujo de trabajo.

Historial de versiones

• Accede a iteraciones pasadas de tus colecciones, entornos y mocks.
• Este registro histórico te permite volver a versiones anteriores si es necesario, proporcionando una red de seguridad en caso de modificaciones no deseadas.

Integración con sistemas de control de versiones externos

• Si bien el sistema integrado de Postman destaca en la gestión de artefactos de API, también puede integrarse con sistemas externos como Git.
• Esta sincronización te permite gestionar los cambios en tus colecciones de Postman junto con tu código base en un único repositorio, promoviendo una fuente unificada de verdad para tus definiciones de API.

Demostración de ejemplo del control de versiones de la API de Postman

Esta demostración de ejemplo del control de versiones de la API en Postman incluirá el uso de un repositorio de Git.

Crear una API en Postman

Crea una nueva solicitud haciendo clic en el botón New en la esquina superior izquierda de la ventana de Postman. Selecciona HTTP Request para crear una nueva solicitud, como se muestra en la imagen anterior.

Introduce el método y los detalles de la API

Incluye los detalles de la solicitud de API que deseas crear. Debe incluir componentes como la URL, los métodos HTTP y los parámetros adicionales que requerirá la API.

Selecciona la configuración del equipo

Continúa haciendo clic en Team Settings.

Selecciona las aplicaciones instaladas

Serás redirigido a una página web para una mayor configuración. En esta página, localiza Installed apps que se encuentra en la lista vertical izquierda. Si tienes GitHub Enterprise Server o GitLab Self-Managed, estas aplicaciones aparecerán en esta pantalla.

Introduce la URL del dominio del repositorio de GitHub

Introduce la URL del dominio de tu repositorio de GitHub, que debería verse algo así:

GitHub Enterprise Server: https://my-github-server.example.com

GitLab Self-Managed: https://gitlab.example.com

Crear una aplicación OAuth

Siguiendo el proveedor de Git que tengas, cumple con las instrucciones para crear una aplicación OAuth.

• URL de la página de inicio - Introduce la URL de la página de inicio de Postman: https://www.postman.com
• URL de devolución de llamada de autorización o URI de redireccionamiento - Introduce la URL de devolución de llamada de autorización proporcionada en Postman: https://integration-oauth.pstmn.io/v1/api-git-callback.html
• Scopes - Asegúrate de seleccionar los scopes apropiados al crear la aplicación OAuth para permitir que Postman lea y escriba en tu repositorio. Para GitHub, selecciona los scopes repo y user. Para GitLab Self-Managed, selecciona el scope api.

Una vez que tengas la aplicación OAuth, copia su ID de cliente y su secreto para introducirlos en Postman.

Colaboración sencilla y directa con Apidog

Apidog es una potente plataforma de desarrollo de API que puede ser un excelente reemplazo para Postman. Con una colaboración fiable y un sistema de control de versiones distintivo nativo de Apidog, los usuarios pueden trabajar juntos en un equipo para desarrollar APIs profesionalmente con eficiencia.

Construyendo APIs con Apidog

Con Apidog, tú y tu equipo podéis crear APIs con unos pocos clics.

Para empezar, pulsa el botón New API, como se muestra en la imagen anterior.

Continúa definiendo las diversas características de la API. Esta sección te permite:

• Especificar el método HTTP: Selecciona el método HTTP apropiado (GET, POST, PUT o DELETE) para dictar la operación del servidor deseada.
• Definir la URL del endpoint de la API: Indica la URL específica del endpoint de la API (o la dirección de la API) que facilita la interacción cliente-servidor.
• Incorporar parámetros (opcional): Incluye uno o más parámetros para que se incluyan dinámicamente dentro de la URL de la API, lo que permite solicitudes personalizadas.
• Proporcionar una descripción funcional: Elabora una descripción concisa que aclare la funcionalidad prevista de la API.

Control de versiones con Apidog

En la sección Diseño de tu API, haz clic en el pequeño icono cuadrado como se muestra en la imagen anterior. Esto te llevará a la sección de registro de cambios de tu API.

En esta lista, puedes seleccionar la actualización que deseas ver.

Por último, puedes observar los cambios realizados de una versión de tu API a otra. Puedes ver cuándo se realizó el cambio y quién lo realizó. Si en algún caso se requiere una versión anterior de la API, los usuarios también tendrán la opción de revertirla a una versión anterior seleccionada.

Conclusión

Aprovechar eficazmente las funcionalidades de control de versiones de Postman permite a los desarrolladores cultivar un entorno de desarrollo de API más organizado y colaborativo. Esta guía te ha proporcionado el conocimiento para rastrear los cambios, facilitar la colaboración en equipo a través de funciones como forking y merging, y mantener un historial claro de las revisiones de la API.

Recuerda, una estrategia de control de versiones bien definida es fundamental para agilizar tu flujo de trabajo, prevenir conflictos y garantizar la evolución fluida de tus APIs. Adopta las funciones integradas de Postman y explora la posible integración con sistemas externos para establecer un enfoque de control de versiones que potencie a tu equipo de desarrollo.