Versionado y estabilidad
Cómo se versiona la API, qué cambios pueden llegar sin una nueva versión mayor y cómo fijarse a v1.
PDF Blocks versiona la API para que pueda adoptar mejoras sin miedo a roturas inesperadas. Las reglas que siguen le dicen exactamente qué cambios es seguro recibir de forma automática y cómo le llegaría cualquier cambio incompatible.
Versionado semántico
La API sigue el versionado semántico 2.0.0. Dado un
número de versión X.Y.Z:
| Parte | Nombre | Significado |
|---|---|---|
X |
Mayor | Cambios no retrocompatibles. |
Y |
Menor | Adiciones de funciones retrocompatibles. |
Z |
Parche | Correcciones de errores retrocompatibles. |
La versión actual de la especificación es 1.18.0. Siempre puede leer la
versión vigente en el campo info.version de la especificación
OpenAPI.
La versión mayor v1 en la ruta
La versión mayor está fijada en la ruta de la URL: todas las acciones
viven bajo /v1/, como en https://api.pdfblocks.com/v1/add_text_watermark.
Las versiones menores y de parche se publican en el mismo lugar, bajo /v1/:
las recibe de forma automática y nunca cambia sus URL para obtenerlas. Como
los cambios incompatibles solo se publican bajo una nueva versión mayor (un
nuevo segmento de ruta), quedarse en /v1/ significa quedarse en un contrato
estable.
Qué cuenta como retrocompatible
Dentro de v1 hacemos cambios aditivos sin una nueva versión mayor.
Considere que todo lo siguiente puede aparecer en cualquier momento y escriba
clientes que lo toleren:
- Parámetros opcionales nuevos en una acción existente.
- Valores aceptados nuevos para un parámetro existente: una enumeración ampliada.
- Alias de parámetros: un nombre nuevo para un campo existente, con el nombre anterior todavía aceptado.
- Respuestas más ricas: campos nuevos en un cuerpo de respuesta o cabeceras de respuesta nuevas.
- Acciones y endpoints nuevos.
Ninguno de estos exige que fije una versión menor ni que cambie su código. Para mantener la compatibilidad, ignore los campos de respuesta que no reconozca en lugar de fallar por ellos, y no dé por sentado un conjunto fijo y exhaustivo de valores de enumeración.
Cómo se publican los cambios incompatibles
Un cambio incompatible, es decir quitar o renombrar un parámetro obligatorio,
cambiar una respuesta de forma incompatible o alterar un comportamiento ya
establecido, solo se publicaría como una nueva versión mayor bajo una ruta
nueva, por ejemplo /v2/. Sus llamadas a /v1/ siguen funcionando sin
cambios y usted migra cuando le convenga. No hacemos cambios incompatibles en
el mismo lugar bajo /v1/.
Fíjese a una versión mayor
Fije su integración a la versión mayor v1 manteniendo /v1/ en las URL de
sus solicitudes. Eso es todo lo que necesita fijar: recibe de forma
automática las mejoras menores y de parche retrocompatibles, mientras que los
cambios incompatibles se mantienen fuera de su ruta hasta que decida adoptar
una versión mayor futura.
Siga lo que cambió en cada versión en el Registro de cambios.