Versionado y política de deprecación de la API

Esta es la política de versionado y deprecación (API versioning & deprecation policy) de la API pública de Ferretería Clarita, que corre sobre ERProva. Es la misma para el dominio del sitio (www.ferreteriaclarita.com.ar) y el del sistema (clarita.ferreteriaclarita.com.ar).

Versión actual

La versión vigente es la 2.0. Va en el header de respuesta API-Version: 2.0 de todos los endpoints públicos, no en la URL. El cliente puede mandar el mismo header en el pedido para fijar la versión que espera; si pide una que esta instancia no sirve, la respuesta es 400 con codigo: DATOS_INVALIDOS, nunca una respuesta silenciosamente distinta.

Qué se considera compatible

Dentro de una misma versión pueden aparecer campos nuevos en las respuestas, endpoints nuevos, parámetros opcionales nuevos y códigos de error nuevos. Nunca cambian dentro de la versión: el nombre y el tipo de los campos existentes, el significado de un codigo de error, el formato { "error", "codigo", "detalle"? } ni la autenticación. Los clientes deben ignorar campos que no conocen.

Cómo se anuncia una deprecación

Un cambio incompatible se publica como una versión nueva y la anterior sigue funcionando durante el período de aviso. Mientras tanto, cada respuesta de la versión deprecada trae los headers Deprecation (fecha en que quedó deprecada) y Sunset (fecha a partir de la cual deja de responder), según RFC 8594. El aviso mínimo es de 90 días entre Deprecation y Sunset; hasta la fecha de Sunset las dos versiones conviven y después la vieja deja de servirse.

Hoy

No hay ninguna versión deprecada ni fecha de sunset anunciada: la 2.0 es la única y no está previsto retirarla. Cuando eso cambie, va a figurar acá, en /openapi.json (campo info.version y deprecated: true en las operaciones afectadas) y en los headers.

Límites y disponibilidad

Los endpoints públicos tienen límite por dirección IP, informado en los headers RateLimit y RateLimit-Policy (hoy 600 pedidos por minuto); al superarlo la respuesta es 429 con codigo: DEMASIADAS_SOLICITUDES y Retry-After. Si el sistema no está disponible, este dominio responde 503 con codigo: NO_DISPONIBLE y Retry-After.

Dónde avisamos

Cambios y deprecaciones se publican en esta página y en /docs; los integradores con clave pueden pedir aviso por e-mail a ferreteriaclarita@gmail.com.