Estabilidad, versionado y obsolescencia de la API
Antes de construir a largo plazo sobre la RealityConnect API, entiende qué partes de la superficie son estables, cómo se marcan las operaciones experimentales, y qué esperar entre actualizaciones.
Operaciones experimentales
Sección titulada «Operaciones experimentales»Algunas operaciones de la referencia de la API llevan un marcador de estabilidad experimental. Busca x-scalar-stability: experimental en una operación dentro del documento OpenAPI (visible como una insignia de estabilidad en la referencia de la API renderizada) para identificarlas. Esto se mantiene sincronizado automáticamente con la API, así que consúltalo ahí en lugar de fiarte de una lista fija aquí.
Las operaciones experimentales son reales y se pueden invocar (no están deshabilitadas ni son solo una vista previa), pero sus rutas, parámetros, payloads, respuestas o disponibilidad pueden cambiar sin las mismas garantías de estabilidad que el resto de la API. Consulta Primeros pasos: Endpoints experimentales para saber cómo trabajar con ellas.
Cuando una operación experimental se estabiliza, eso se anuncia en las notas de versión.
Cambios disruptivos y no disruptivos
Sección titulada «Cambios disruptivos y no disruptivos»| Cambio | ¿Disruptivo? | Por qué |
|---|---|---|
| Nuevo parámetro de solicitud opcional | No | Las solicitudes existentes siguen funcionando sin cambios |
| Nuevo campo de respuesta | No | Los clientes existentes que leen campos conocidos no se ven afectados; procesa las respuestas de forma tolerante e ignora los campos no reconocidos |
| Nuevo valor de enumeración añadido a un campo existente | No | Trata los campos de enumeración como conjuntos abiertos y maneja con flexibilidad los valores no reconocidos, en lugar de comparar exhaustivamente cada valor conocido |
| Campo existente eliminado o renombrado | Sí | Rompe a cualquier cliente que lea ese campo |
| Tipo o significado de un campo existente modificado | Sí | Rompe a cualquier cliente que dependa de la forma anterior |
| Parámetro requerido añadido a una operación existente | Sí | Rompe las solicitudes existentes que no lo envían |
| Ruta del endpoint o método HTTP modificado | Sí | Rompe directamente las solicitudes existentes |
| El contrato de una operación experimental cambia | No (intencional) | Las operaciones experimentales están explícitamente exentas del contrato de estabilidad; ver arriba |
Política de obsolescencia
Sección titulada «Política de obsolescencia»Antes de eliminarse, una operación estable se marca como obsoleta con una fecha de retiro (sunset). La referencia de la API marca la operación como obsoleta, y su definición OpenAPI incluye deprecated: true y la fecha de retiro en x-sunset (YYYY-MM-DD).
- Una operación estable obsoleta sigue funcionando hasta su fecha de retiro, y puede eliminarse a partir de esa fecha.
- No existe un plazo mínimo de aviso fijo: la fecha de retiro de cada obsolescencia es su aviso.
- Un parámetro de solicitud obsoleto con fecha de retiro sigue la misma regla.
- Algunos parámetros de consulta se renombran con un alias retrocompatible: el nombre anterior sigue funcionando junto al nuevo.
- Las operaciones experimentales están exentas: pueden marcarse como obsoletas sin fecha de retiro, y cambiarse o eliminarse sin aviso, según Operaciones experimentales.
¿Qué sigue?
Sección titulada «¿Qué sigue?»- Consulta la referencia de la API para el marcador de estabilidad actual y el esquema de solicitud y respuesta de cada operación.
- Consulta Primeros pasos para el modelo de seguridad y cómo elegir un flujo OAuth.