Las API abiertas son una herramienta crucial para que los equipos técnicos compartan servicios y datos con los usuarios. A medida que las empresas crecen y la tecnología evoluciona, las API deben actualizarse regularmente. Estas actualizaciones suelen estar diseñadas para satisfacer las nuevas demandas del mercado, mejorar las funciones existentes, añadir nuevas funcionalidades o abordar las vulnerabilidades de seguridad.
Dado que a menudo se requiere que varias versiones de una API se ejecuten simultáneamente, los equipos deben gestionar estas versiones de forma eficaz. Algunos usuarios pueden necesitar la última versión para acceder a las nuevas funciones, mientras que otros podrían preferir la estabilidad y la familiaridad de las versiones anteriores.
Para satisfacer estas diversas necesidades, los equipos suelen proporcionar varias versiones de la API, como las versiones más recientes, estables o de soporte a largo plazo. Esto ayuda a garantizar la compatibilidad y la estabilidad para los diferentes grupos de usuarios, minimizando la interrupción causada por las actualizaciones para los usuarios que dependen de versiones anteriores.
La función de versiones de API de Apidog está diseñada para facilitar la gestión de varias versiones. Permite a los equipos crear, gestionar y mantener diferentes versiones de API, garantizando que cada versión funcione de forma independiente y sea claramente distinta de las demás.
Guía paso a paso para crear versiones de API
Paso 1: Crear una versión de API
Una vez que entre en su proyecto, vaya al conmutador de ramas situado encima de la carpeta del proyecto y seleccione API Versions para ver todas las versiones del proyecto actual. Haga clic en New API Version para crear una nueva versión. Asigne un nombre a la versión y seleccione el contenido inicial.
Después de guardar, el sistema cambiará automáticamente a la nueva versión, lo que le permitirá editar los recursos para esa versión sin afectar a la versión original.
Paso 2: Publicar versiones de API en la documentación
Una vez creada la versión de la API, vaya a la sección "Share Docs -> Publish Doc Sites" del proyecto.
Haga clic en Edit para elegir qué versión de API publicar. Puede especificar la fuente de la versión, mostrar los números de versión, establecer los entornos de ejecución y configurar el slug.
slug sirve como identificador único para una versión de API específica que sigue la dirección de acceso público. Por ejemplo, en la URL https://example.Apidog.cn/2-0-0, 2-0-0 es el Slug, lo que permite a los usuarios externos acceder directamente a esa versión específica de la API. Esto garantiza que cada versión de la API tenga una ruta de acceso única y clara.También puede reordenar las versiones publicadas. La primera versión de la lista será la versión predeterminada, que se mostrará a los usuarios que accedan al proyecto sin especificar una versión.
Después de completar estos ajustes, haga clic en Publish. El proyecto se marcará como Published y los usuarios podrán acceder a la documentación de la API a través del enlace de documentación, donde podrán cambiar entre las diferentes versiones.
Paso 3: Compartir rápidamente los puntos finales en las versiones de API
Además de publicar versiones de API, también puede compartir puntos finales específicos de cualquier versión de la API.
Para ello, cree un enlace para compartir, seleccione la versión de la API y elija los puntos finales que desea compartir.
Una vez generado el enlace para compartir, los usuarios pueden ver los puntos finales seleccionados para esa versión de la API.
Paso 4: Eliminar versiones de API
Para eliminar una versión de API, vaya a "Project Settings -> API Versions" en la rama principal.
Una vez eliminada, la documentación pública ya no incluirá esa versión y los enlaces para compartir asociados a esa versión dejarán de ser válidos. Esto garantiza que los usuarios ya no puedan acceder al contenido de la versión eliminada a través de esos enlaces.
Preguntas frecuentes sobre el control de versiones de la API
1. ¿Cuál es la diferencia entre las versiones de API y las ramas de sprint?
Versiones de API: Se utilizan principalmente para la publicación externa. Es mejor crear una nueva versión cuando se realizan cambios importantes que son incompatibles con la versión anterior. Las versiones de API incluyen un conjunto completo de puntos finales.
Ramas de sprint: Se utilizan para el desarrollo interno del equipo. Se crea una nueva rama para cada iteración y se fusiona en la rama principal una vez completada. Las ramas de sprint suelen contener solo puntos finales nuevos o modificados.
2. ¿La función de versión de API es compatible con todos los tipos de proyectos?
Actualmente, la función solo es compatible con proyectos HTTP.
3. ¿Quién puede crear y modificar versiones de API?
Los administradores y editores de proyectos pueden crear y modificar versiones de API.
4. ¿Quién puede publicar o eliminar versiones de API?
Solo los administradores de proyectos pueden publicar o eliminar versiones de API.
5. ¿Los cambios en una versión de API afectarán a otra?
No. Cada versión de API funciona de forma independiente, por lo que los cambios en los recursos de una versión no afectarán a otras versiones.
6. ¿Hay planes para admitir más funciones, como la compatibilidad multilingüe?
Sí, estamos trabajando activamente en funciones como la compatibilidad multilingüe y las extracciones entre ramas/versiones. Estas se añadirán en futuras versiones para mejorar la gestión de la documentación de la API.
7. ¿Qué pasa con las mejoras para las ramas de sprint?
Hay actualizaciones en curso para las funciones de la rama de sprint, incluida la capacidad de copiar recursos de otras ramas, seleccionar recursos de otras ramas, revisar la fusión de ramas y bloquear ramas. Estas mejoras estarán disponibles en las próximas actualizaciones.
Conclusión
La función de control de versiones de API de Apidog facilita a los equipos la creación, gestión y mantenimiento de varias versiones de sus API. Esto garantiza que las versiones antiguas sigan siendo estables mientras se introducen nuevas funciones. Tanto si gestiona una sola API como varias versiones para diferentes grupos de usuarios, Apidog agiliza el proceso, garantizando la compatibilidad y minimizando las interrupciones para los usuarios.
