Directivas de Data API Builder
Un conjunto de directivas rige el generador de Api de datos relacionado con los cambios importantes, las notificaciones, las versiones y el control de versiones.
Control de versiones y versiones
Una versión en el contexto de Data API Builder hace referencia a todas las versiones publicadas del software, identificadas por el Major.Minor.Patch formato . Estas versiones se dividen en tres categorías: estable, cambio importante y versión preliminar.
Versiones estables
Una versión estable de Data API Builder es compatible con versiones anteriores. La compatibilidad con versiones anteriores implica que cualquier código que escriba que se base en una versión de un generador de Data API puede adoptar una versión estable más reciente sin necesidad de cambios de código para mantener la corrección o la funcionalidad existente.
Versiones de cambios importantes
Una versión de cambio importante del generador de Data API no es compatible con versiones anteriores. La adopción de una versión de cambio importante en el código de cliente existente podría requerir cambios de código para asegurarse de que el cliente se comporta exactamente igual que cuando tenía como destino la versión anterior.
Las versiones de cambios importantes se anuncian a través del artículo de la lista de cambios importantes y en la descripción del cambio de una versión de GitHub. La publicación de una versión preliminar o una versión candidata para lanzamiento precede a las versiones de cambios importantes a menos que los cambios corrijan problemas críticos de seguridad, privacidad o legales. Aunque es posible que las versiones anteriores de Data API Builder sigan estando disponibles en la página de versiones de GitHub, se recomienda actualizar a la versión más reciente, lo que podría incluir correcciones de errores.
Versiones preliminares
Las versiones preliminares de Data API Builder se identifican con el X.Y.Z-rc esquema de control de versiones. El -rc sufijo indica que la compilación es una "versión candidata para lanzamiento". Las versiones preliminares se usan para recopilar comentarios sobre las nuevas características y otros cambios.
A menos que tengamos previsto realizar cambios significativos a partir de la última versión estable, publicamos la siguiente versión preliminar con todo, desde la versión estable más reciente y las nuevas características en versión preliminar. La siguiente actualización del Generador de API de datos podría interrumpir algunas de las nuevas características en versión preliminar que hemos agregado entre las versiones preliminares. Este comportamiento importante significa que es posible que tenga que cambiar el código para que las cosas vuelvan a funcionar.
Las versiones preliminares no están pensadas para el uso a largo plazo o de producción. Cuando haya disponible una nueva versión estable o preliminar, es posible que las versiones preliminares anteriores ya no sean accesibles. Es mejor usar versiones preliminares solo cuando esté trabajando activamente en nuevas características y esté listo para cambiar a una versión no preliminar poco después de la versión. Si algunas características de una versión preliminar se incluyen en una nueva versión estable, las demás características en versión preliminar se agregan a una nueva versión preliminar para que pueda probar.
Tabla de cambios de versión
Importante
Podríamos introducir un cambio importante en una versión secundaria o de revisión cuando el cambio soluciona errores críticos del producto, problemas legales, de seguridad o privacidad.
| Tipo de versión | Versión anterior | Versión nueva | Notas |
|---|---|---|---|
| Cambio problemático | 1.Y.Z |
2.Y.Z |
Nuevas características y correcciones de errores junto con los cambios importantes. |
| Stable | 1.1.Z |
1.2.Z |
Las nuevas características y correcciones de errores sin cambios importantes a menos que los cambios aborden errores críticos del producto, legales, de seguridad o de privacidad. |
| Stable | 1.1.1 |
1.1.2 |
Correcciones de errores sin nuevas características ni cambios importantes a menos que los cambios aborden errores críticos del producto, legales, de seguridad o de privacidad. |
| Vista previa | X.Y.1-rc |
X.Y.2-rc |
Nuevas características en versión preliminar y correcciones de errores. (Los cambios importantes se incluyen si se ha producido un aumento de la versión principal). |
Últimos cambios
Para priorizar la seguridad, mejorar las características y mantener la calidad del código, las nuevas versiones de nuestro software pueden incluir cambios importantes. Aunque nos esforzamos por minimizar estos cambios a través de opciones arquitectónicas cuidadosas, todavía pueden producirse. En tales casos, hacemos que sea una prioridad anunciarlos y proporcionar posibles soluciones.
Importante
Es posible que realicemos cambios sin previo aviso si el cambio se considera no importante o si se trata de un cambio importante para abordar errores críticos del producto o problemas legales, de seguridad o de privacidad.
¿Qué es un cambio importante?
Un cambio importante es una modificación que requiere que actualice la aplicación para evitar interrupciones. En el generador de Api de datos, los cambios importantes pueden incluir modificaciones en los contratos de la API REST, la generación de esquemas graphQL y otros elementos que afectan a la compatibilidad y la funcionalidad.
Ejemplos de cambios importantes
Los ejemplos siguientes son una lista inexistente de cambios importantes en Data API Builder:
- Modificaciones del contrato de LA API REST
- Modificaciones en la generación de esquemas de GraphQL
- Cambios que afectan a la compatibilidad con versiones anteriores
- Eliminación o cambio de nombre de api o parámetros
- Cambios en los códigos de error
- Ajustes en la funcionalidad de definición de permisos
- Eliminación de parámetros permitidos, campos de solicitud o campos de respuesta
- Adición de parámetros obligatorios o campos de solicitud sin valores predeterminados
- Modificaciones en la funcionalidad de punto de conexión de API prevista
Definición de un cambio de no separación
Un cambio no importante hace referencia a un cambio que se puede integrar en la aplicación sin causar interrupciones. Los cambios de no separación se suelen comunicar después de la implementación. La aplicación debe diseñarse para controlar estos cambios sin previo aviso.
Ejemplos de cambios no importantes
Los ejemplos siguientes son una lista no exhaustiva de cambios de no separación en data API Builder:
- Introducción de nuevos puntos de conexión
- Adición de métodos a los puntos de conexión existentes
- Incorporación de nuevos campos en respuestas y solicitudes
- Ajustes en el orden de los campos dentro de las respuestas
- Introducción de encabezados de solicitud opcionales
- Cambios en la longitud y el tamaño de respuesta de los datos
- Modificaciones en los mensajes de error y códigos
- Correcciones en códigos de respuesta HTTP
- Metadatos adicionales en documentos de OpenAPI generados
¿Cómo se comunican los cambios importantes?
Lo hacemos una prioridad para informarle rápidamente sobre los cambios importantes. Puede encontrar notificaciones de cambios importantes en las notas de la versión de las versiones de Data API Builder en GitHub y, en el artículo de la lista de cambios importantes dedicados.
Lista de cambios importantes actual
En este artículo se anuncian cambios importantes y retiradas de características.
- A partir de ahora, no hay cambios importantes