Versionado

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).

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): desde cuándo está obsoleto.
• Sunset (RFC 8594): 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. Hoy ningún endpoint está obsoleto.