Iterar y mantener las APIs es crucial durante el desarrollo del producto. A medida que los productos evolucionan con nuevas características o ajustes, las actualizaciones o modificaciones correspondientes de la API se vuelven necesarias, especialmente en entornos de ritmo rápido.
Sin embargo, la iteración de la API no siempre es sencilla. La gestión de las APIs junto con las actualizaciones o modificaciones del producto a menudo presenta desafíos:
- ¿Cómo iterar y probar las APIs de manera efectiva, garantizando al mismo tiempo la estabilidad de las APIs existentes?
- ¿Cómo gestionar las APIs a través de múltiples iteraciones de desarrollo paralelas, evitando interferencias?
Para abordar estos escenarios, Apidog introduce la función "Sprint Branch". Esta funcionalidad proporciona una forma flexible de gestionar las APIs, permitiéndote iterar, actualizar y desarrollar nuevas características en ramas independientes sin afectar la estabilidad de las APIs en línea en la rama principal.
La función Sprint Branch admite el control de versiones, la colaboración paralela y la fusión rápida. Cada rama es una versión independiente, lo que evita interferencias, y los cambios dentro de una rama se pueden fusionar rápidamente de nuevo en la rama principal.
Comprendiendo los casos de uso de la rama Sprint
La función "Sprint Branch" te permite crear múltiples ramas de desarrollo dentro de un proyecto para actualizar, iterar y probar las APIs en diferentes etapas sin afectar la rama principal (es decir, la versión estable actual).
Cuándo considerar el uso de la rama Sprint:
- Desarrollo y prueba de características: Desarrolla y prueba nuevas características en una nueva rama Sprint sin afectar la versión estable en la rama principal.
- Actualizaciones y corrección de errores: Actualiza las APIs o corrige errores en una rama dedicada, fusionándolos en la rama principal después de una prueba exitosa.
- Experimentación y validación: Realiza modificaciones experimentales en las APIs, verificando su eficacia antes de decidir si fusionarlas en la rama principal.
Cuándo no usar las ramas Sprint:
- Para actualizaciones menores de la API o correcciones de errores simples, podría ser más conveniente operar directamente en la rama principal.
- Si tu negocio requiere proporcionar múltiples versiones de API para usuarios externos, se recomienda utilizar la función "Control de versiones de API" para garantizar la estabilidad y la coherencia para los usuarios externos.
A continuación, se muestra una breve introducción a la función "Sprint Branch". Para obtener instrucciones de uso más detalladas, consulta el módulo Sprint Branch en la documentación de ayuda. Antes de comenzar, asegúrate de que Apidog esté actualizado a la última versión.
Creando una rama Sprint
Si tu rol en el proyecto es "Administrador" o "Editor", puedes crear una nueva rama Sprint para comenzar el trabajo relacionado con la iteración haciendo clic en la opción "Nueva rama Sprint" en el componente "Sprint Branch" en la esquina superior derecha del árbol de directorios.
Diseñando APIs en una rama Sprint
La función Sprint Branch de Apidog solo cubre el contenido modificado o recién agregado durante la iteración. Por lo tanto, la nueva rama Sprint está inicialmente vacía y debes seleccionar el contenido que se va a modificar o agregar.
Los recursos importados, incluidas las APIs, los casos de uso de la API y los modelos de datos, tendrán un identificador de asociación claro con la rama principal. Los recursos recién creados dentro de la rama Sprint no tendrán un identificador de asociación.
Durante el proceso de diseño de la API, también puedes comparar un recurso específico de la rama Sprint asociado con la rama principal para ver las diferencias entre el recurso y la rama principal.
Probando APIs en una rama Sprint
La función "Pruebas" también es compatible con las ramas Sprint. Puedes crear nuevos "Nuevos escenarios de prueba" o importar los existentes desde la rama principal.
En el árbol de directorios, los escenarios de prueba importados tendrán identificadores de asociación claros con los recursos en la rama principal, de forma similar a los identificadores de recursos en "APIs".
Puedes organizar escenarios de prueba en una rama Sprint al igual que en la rama principal. Dado que los escenarios de prueba pueden involucrar APIs tanto de la rama Sprint como de la rama principal, el sistema utilizará "iconos de rama" para distinguir qué recursos (rama Sprint o rama principal) se utilizan en cada paso de la prueba.
Cuando haces clic para ver los detalles de estos pasos, también puedes ver a qué rama pertenecen sus recursos asociados.
Una vez que las APIs y los escenarios de prueba relevantes en la rama están diseñados y organizados, puedes probarlos.
El sistema utilizará los datos correspondientes en función de la fuente de recursos identificada en los pasos para las pruebas automatizadas. Si un paso de prueba se identifica como el uso de recursos de la rama Sprint, la prueba utilizará datos de la rama Sprint; si se identifica como el uso de recursos de la rama principal, la prueba utilizará datos de la rama principal.
Fusionando una rama Sprint
Después de completar el desarrollo de la API y la implementación exitosa en la rama Sprint, puedes fusionar estos cambios en la rama principal. El contenido fusionado se puede cambiar a algunas o todas las APIs.
La entrada de fusión se encuentra en el "Menú desplegable del componente Rama" en la esquina superior derecha del árbol de directorios. También puedes ver el botón "Fusionar con la rama principal" debajo del árbol de directorios en las APIs.
Al hacer clic en el botón "Fusionar con la principal" en las APIs, se abrirá la ventana emergente de descripción general de la fusión. En la ventana emergente, puedes ver los recursos modificados o todos los recursos entre la rama Sprint actual y la rama principal. También puedes elegir cómo ajustar el estado de los recursos en la rama principal después de la fusión (por ejemplo, "En desarrollo", "En prueba", "Publicado", etc.).
Al hacer clic en un recurso en el árbol de directorios, se expandirá para mostrar su contenido detallado, lo que te ayudará a decidir si fusionarlo. Los diferentes tipos de recursos tendrán una lógica de fusión diferente.
Después de la fusión, un mensaje mostrará los recursos modificados en la rama principal.
Visualización y reversión de fusiones en la rama principal
En las "APIs" de la rama principal, puedes ver los cambios provocados por las operaciones de fusión recientes comprobando el historial de recursos. También puedes ver de qué rama proviene la fusión.
Puedes ver el contenido de modificación específico y compararlo con otras versiones. Esta función de historial te permite rastrear el historial de cambios y revertir el contenido cuando sea necesario.
Archivado, restauración y eliminación de ramas
Después de fusionar una rama, puedes acceder a la página de administración de la rama Sprint a través de "Configuración" -> "Ramas Sprint". En la página de administración, puedes ver una lista de todas las ramas Sprint en el proyecto y sus estadísticas. También puedes realizar varias operaciones en estas ramas, incluido el archivado, la restauración y la eliminación de ramas de iteración.
Preguntas frecuentes sobre las ramas Sprint en Apidog
1 ¿Todos los tipos de APIs son compatibles con la función Sprint Branch?
Actualmente, solo se admiten las APIs HTTP.
2. ¿Quién puede crear una rama de iteración?
Administradores y editores del proyecto.
3. ¿Quién puede acceder a una rama de iteración?
Administradores, editores y miembros de solo lectura del proyecto.
4. ¿Quién puede fusionar los cambios de una rama de iteración?
Administradores y editores del proyecto.
5. ¿Se puede fusionar una rama de iteración en otra rama de iteración?
Actualmente no es compatible. Solo se admite la fusión en la rama principal.
6. Cuando se trabaja en una rama de iteración, si la API en la rama principal también cambia, ¿qué sucederá después de la fusión?
Después de la fusión, los cambios en la rama de iteración sobrescribirán los cambios realizados en la misma API en la rama principal. Esto significa que cualquier adición, eliminación o modificación a la API en la rama principal será reemplazada por el contenido en la rama de iteración.
7. ¿Hay alguna forma de extraer las últimas actualizaciones de la rama principal a una rama de iteración?
Esta función está en desarrollo y estará disponible pronto.
8. Si algunos recursos se eliminan en la rama de iteración, ¿qué impacto tendrá en la rama principal cuando se fusionen?
Si se eliminan recursos completos como APIs o modelos de datos, significa que estos recursos ya no están asociados con la rama principal. Por lo tanto, los recursos correspondientes en la rama principal no se verán afectados durante la fusión, lo que equivale a que no haya cambios.
Esto se debe a que un principio fundamental de las ramas Sprint es solo involucrar la modificación y la adición de recursos. Las operaciones de eliminación deben realizarse directamente en la rama principal, y la rama Sprint no maneja las operaciones de eliminación.
Si los recursos de la API o del modelo de datos en la rama Sprint están asociados con la rama principal, y eliminas algunos de los recursos (por ejemplo, parámetros, descripciones), los recursos correspondientes en la rama principal también se eliminarán después de la fusión. Esta operación es equivalente a modificar los recursos en la rama de iteración.
9. Si se crea una nueva API con la misma URL y parámetros que una API en la rama principal en la rama de iteración, ¿qué sucederá después de la fusión?
Aunque la API recién creada en la rama Sprint tiene la misma URL y parámetros que la API en la rama principal, no están asociadas de forma predeterminada. Después de la fusión, la rama principal agregará esta nueva API que es exactamente la misma que la de la rama Sprint, incluso si ya existe una API con la misma URL y parámetros en la rama principal.
Por lo tanto, si deseas actualizar, probar o modificar una API existente, importa la API desde la rama principal para asegurarte de que estén asociadas. De esta manera, si la API cambia, la API en la rama principal también se actualizará sincrónicamente después de la fusión.
10. ¿Puedo revertir y restaurar el contenido de una rama Sprint anterior?
Sí.
Si necesitas ver el contenido de una iteración anterior por alguna razón, puedes restaurarla del estado archivado al estado de rama normal (ten en cuenta el límite de la rama Sprint).
Después de la restauración, puedes acceder a la rama nuevamente en el árbol de directorios de las APIs. Los datos en la rama antes del archivado se conservarán automáticamente sin cambios. Si deseas restaurar el contenido del historial de la rama, puedes usar directamente esta rama para fusionarla nuevamente en la rama principal para completar la restauración.
Para recursos individuales, se recomienda utilizar la función "Historial" directamente en "APIs" para la reversión y la restauración.
11. ¿Puedo compartir la documentación de la API de una rama Sprint con otros?
Para la colaboración y el intercambio internos, puedes compartirla con los miembros que se han unido al proyecto a través de "Copiar enlace de colaboración". Actualmente, no se admite el intercambio externo de documentación de la API.
Conclusión
La función "Sprint Branch" de Apidog optimiza el proceso de diseño y prueba de la API. Al crear ramas independientes, los equipos pueden desarrollar nuevas características, corregir errores y experimentar sin interferir con la rama principal.
