# Versionado

> Versión Markdown de https://docs.preciosgasolina.es/conceptos/versionado/ · Actualizado: 2026-10-07 · Índice para LLM: https://docs.preciosgasolina.es/llms.txt

Versionado de la API de Gasolina hoy: v1 en la ruta, cambios compatibles sin aviso, cambios incompatibles en una nueva versión, Deprecation y Sunset.

La API está en la versión **`v1`**, que va en la ruta (`https://api.preciosgasolina.es/v1/…`) y en cada respuesta (`meta.api_version`). El OpenAPI (`info.version`) y el servidor MCP (`serverInfo.version`) tienen además su propia versión semántica.

## Cambios compatibles (sin aviso previo)

Dentro de `v1` se pueden hacer, sin cambiar de versión, cambios que no rompen un cliente bien escrito:

- Añadir endpoints, herramientas MCP, recursos o prompts.
- Añadir **campos nuevos** en `data` o en `meta`.
- Añadir **parámetros opcionales** nuevos.
- Añadir valores nuevos a listas abiertas (por ejemplo, nuevos tipos de resultado en `/v1/search` o nuevos códigos `*_NOT_FOUND`).
- Cambiar los textos de `title`, `detail`, `note` y otros textos legibles.
- Ajustar los límites y topes (se anotan en el [registro de cambios](https://docs.preciosgasolina.es/changelog/)).

Para que tu cliente no se rompa:

- **Ignora los campos que no conozcas** (no valides la respuesta con un esquema estricto que rechace campos extra).
- Comprueba `code` en los errores, no `detail`.
- No dependas del orden de los campos de un objeto.

Ojo: la API sí es estricta con lo que *recibe*. Un parámetro desconocido devuelve `400`, así que no envíes parámetros que el endpoint no documente.

## Cambios incompatibles

Quitar o renombrar un endpoint, un campo o un parámetro, o cambiar su tipo o su significado, solo se hará en una **nueva versión** (`/v2/`), que convivirá con `v1` durante un periodo de transición.

## Obsolescencia: `Deprecation` y `Sunset`

Cuando un endpoint vaya a retirarse, sus respuestas llevarán las cabeceras estándar:

- `Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)): desde cuándo está obsoleto.
- `Sunset` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)): fecha a partir de la cual dejará de funcionar.
- `Link` con `rel="deprecation"`: página con la explicación y la alternativa.

El OpenAPI marcará esas operaciones con `deprecated: true` y el cambio se anunciará en el [registro de cambios](https://docs.preciosgasolina.es/changelog/). Hoy ningún endpoint está obsoleto.