Estabilidad y versionado 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 |
¿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.