ETAR · API v1
ETAR: política de versiones y deprecación de la API
La API de contenido público usa versiones mayores en la URL. /api/v1/content está activa. No se anunció ninguna fecha de deprecación ni de retiro.
Compatibilidad dentro de v1
Los significados y tipos de los campos existentes y el acceso público se mantienen compatibles dentro de v1. Se pueden agregar campos opcionales y enlaces; los clientes deben ignorar los campos desconocidos. Las páginas y los documentos publicados pueden cambiar o retirarse mediante revisión editorial. Una lista vacía es válida y no implica que la API esté fuera de servicio.
Cambios incompatibles y migración
Un cambio planificado incompatible con el contrato requiere una nueva URL mayor, por ejemplo /api/v2/content. Antes de un retiro planificado, ETAR publicará en esta página los endpoints afectados, la versión de reemplazo, las instrucciones de migración y las fechas de deprecación y retiro. El plazo de aviso se indicará en ese anuncio; actualmente no se promete un período fijo de soporte. Las correcciones de seguridad o privacidad pueden requerir restricciones inmediatas.
Señales Deprecation y Sunset
Las respuestas enlazan esta política mediante Link: <URL de la política>; rel="deprecation"; type="text/html", según RFC 9745. Cuando se anuncie una deprecación, las respuestas afectadas usarán Deprecation con una fecha Structured Field de RFC 9745: @ seguido de los segundos Unix. Cuando se programe un retiro, Sunset usará una fecha HTTP en GMT, según RFC 8594. La fecha de retiro no será anterior a la de deprecación.
Actualmente las respuestas de v1 omiten ambas cabeceras de fecha porque la versión sigue activa. Los clientes deben seguir el enlace a esta política y revisar las cabeceras tanto en respuestas correctas como en errores, incluido HEAD. Deben migrar antes del retiro anunciado y no deducir una fecha cuando no exista la cabecera.
Alcance e historial
Esta política abarca el contrato REST. MCP negocia sus propias versiones de protocolo; la CLI tiene versiones semánticas independientes. Ninguno cambia el alcance de solo lectura de la API. La versión del documento OpenAPI identifica su revisión; /v1/ identifica la versión mayor estable de la API.
- API v1: activa; deprecación: ninguna; retiro: ninguno.
- OpenAPI 1.1.0: agrega enlaces a MCP, la descarga de la CLI y esta política. Los campos y operaciones existentes siguen siendo compatibles.