> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ventry.es/llms.txt
> Use this file to discover all available pages before exploring further.

# Versionado

> Qué puede cambiar sin avisar y qué no.

La API está versionada en la ruta: `/v1`. Mientras exista `v1`, el contrato de
esta documentación se mantiene.

## Cambios compatibles

Estos pueden ocurrir **en cualquier momento y sin aviso previo**. Tu integración
debe tolerarlos:

* Añadir **campos nuevos** a una respuesta.
* Añadir **endpoints** nuevos.
* Añadir **parámetros opcionales** a una petición.
* Añadir **valores nuevos** a un enumerado (por ejemplo, un estado de pulsera).
* Cambiar la **redacción** de un `message` de error.
* Cambiar el **orden** de las claves de un objeto JSON.

<Warning>
  En la práctica esto significa dos cosas concretas: **no valides tus respuestas
  con esquemas estrictos** que rechacen campos desconocidos, y **no supongas que un
  enumerado está cerrado**. Si tu código hace `switch (status)` sin rama por
  defecto, un estado nuevo lo romperá.
</Warning>

## Cambios incompatibles

Nunca ocurren dentro de `v1`. Requieren una versión nueva:

* Eliminar o renombrar un campo de una respuesta.
* Eliminar un endpoint.
* Hacer obligatorio un parámetro que era opcional.
* Cambiar el tipo de un campo.
* Cambiar el `code` de un error, o el código HTTP con el que se devuelve.

## Si llega una `v2`

* `v1` seguirá funcionando durante **al menos 12 meses** desde el anuncio.
* El aviso llegará por correo a la dirección de contacto de tu integración.
* Ambas versiones convivirán: podrás migrar endpoint a endpoint.

## Comprobar contra qué estás integrando

El documento OpenAPI vive en la propia instalación y siempre corresponde al
código desplegado:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.ventry.es/v1/openapi.json | jq '.info.version'
  ```

  ```js Node.js theme={null}
  const spec = await (
    await fetch("https://api.ventry.es/v1/openapi.json")
  ).json();

  console.log(spec.info.version);
  ```

  ```python Python theme={null}
  spec = requests.get("https://api.ventry.es/v1/openapi.json", timeout=10).json()

  print(spec["info"]["version"])
  ```

  ```php PHP theme={null}
  $spec = json_decode(
      file_get_contents("https://api.ventry.es/v1/openapi.json"),
      true
  );

  echo $spec["info"]["version"];
  ```
</CodeGroup>

No hace falta autenticarse para leerlo.

También hay una referencia navegable en `https://api.ventry.es/v1/docs`.