Versionado de la API

La API pública usa versiones con fecha, el mismo esquema que Shopify, de modo que la versión sobre la que desarrollas no cambia bajo tus pies. Las versiones con fecha son la frontera gruesa para los cambios incompatibles; dentro de una versión el esquema sigue evolucionando solo por adición.

Nombres de versión

Una versión se llama YYYY-MM, donde el mes es un inicio de trimestre: 2026-01, 2026-04, 2026-07, 2026-10. Solo se publica una nueva versión con fecha cuando hay un cambio incompatible; los trimestres sin cambios incompatibles se omiten, por lo que las versiones son relativamente escasas.

También existe una versión unstable que sigue el filo del desarrollo y permite previsualizar cambios antes de una publicación estable. No construyas integraciones de producción sobre ella.

Seleccionar una versión

Dos maneras, por orden de prioridad:

1. Ruta de la URL (recomendado): pon la versión en el endpoint — …/backend/<subdomain>/api/2026-07/graphql. Es explícito, amigable con la caché y fácil de copiar y pegar.
2. Cabecera de la petición: envía X-Api-Version: 2026-07 al endpoint simple …/backend/<subdomain>/graphql.

Si omites la versión —o indicas una desconocida o que ya pasó su fecha de retirada—, la petición la atiende la versión más antigua todavía soportada, nunca la más reciente. Nunca se te actualiza en silencio a un cambio incompatible. Fija una versión de forma explícita en cualquier integración que pienses mantener.

Cada respuesta indica la versión que la atendió en una cabecera X-Api-Version, así siempre sabes qué contrato respondió y puedes detectar desviaciones si dependías del comportamiento por defecto.

Periodo de soporte

Cada versión estable se soporta durante al menos 12 meses, con al menos 9 meses de solapamiento con la siguiente. En la práctica hay dos o tres versiones activas en cualquier momento, lo que deja una ventana cómoda para migrar. La fecha de retirada de una versión se publica el mismo día en que sale.

Qué cuenta como cambio incompatible

Dentro de una misma versión podemos hacer cambios por adición, y tu cliente debe tolerarlos:

• añadir un nuevo tipo, consulta o mutación;
• añadir un argumento opcional a un campo existente;
• añadir un campo a un tipo de objeto;
• añadir un valor a una enumeración (por tanto, nunca supongas que una enumeración está cerrada).

Una nueva versión con fecha se reserva para cambios realmente incompatibles: eliminar o renombrar un campo o un tipo, endurecer la nulabilidad, o cambiar el significado de un argumento o de un valor por defecto. Estos nunca ocurren dentro de una versión existente: la versión que fijaste mantiene su comportamiento hasta su fecha de retirada.

Obsolescencias

Las obsolescencias se señalan de dos maneras, para que te enteres antes de que algo se rompa:

• En el esquema. Un campo que se retira se marca con @deprecated y una razón que nombra su sustituto. La introspección y el GraphQL Playground lo muestran automáticamente a cualquier cliente.
• En la respuesta. Cuando una petición resuelve realmente un campo obsoleto, la respuesta incluye la cabecera X-Api-Deprecated-Reason (y una entrada extensions.deprecations equivalente) que nombra las obsolescencias concretas que tocó, de modo que una obsolescencia aparece en tus registros en cuanto la encuentras, sin tener que buscarla.

Un campo obsoleto se mantiene durante un periodo mínimo publicado antes de eliminarse en una versión con fecha posterior.