Versiones y obsolescencia

La API REST de Rhombus tiene una sola versión. No hay encabezado de versión ni versión en la URL: cada operación está en /api/<servicio>/<operación>.

Nuevas versiones de una operación

Cuando una operación tiene que cambiar de una forma que rompería a los clientes existentes, Rhombus agrega una operación nueva con un sufijo de versión y conserva la anterior. Por ejemplo, spliceV3 convive con splice y spliceV2, y getSavedClipsV2 con getSavedClips. Usa la versión más alta que exista, salvo que la referencia indique otra cosa.

Operaciones obsoletas

La operación anterior se marca entonces como obsoleta:

• La referencia de la API (en inglés) la marca como Deprecated y, cuando existe, enlaza al reemplazo. La barra lateral oculta las operaciones obsoletas salvo que actives Show deprecated operations.
• La especificación OpenAPI la marca con deprecated: true, así que los clientes generados también la señalan.

Las operaciones obsoletas siguen funcionando, pero no reciben funciones nuevas. Pasa al reemplazo la próxima vez que trabajes en esa parte de tu integración. Si una operación se retira, responde con "error": true y un errorMsg que lo indica; consulta Errores.

Encabezados Deprecation y Sunset

Cuando una forma de llamar a la API va a dejar de funcionar, las respuestas a las solicitudes que todavía la usan incluyen dos encabezados:

Deprecation: true
Sunset: Tue, 05 Jan 2027 00:00:00 GMT

• Deprecation: true significa que la solicitud dependió de algo obsoleto. La solicitud en sí tiene éxito.
• Sunset es la fecha a partir de la cual la misma solicitud falla con un error.

Por ejemplo, una credencial de partner que llama a un endpoint fuera de /api/partner/ sin el encabezado x-auth-org recibe estos encabezados, con la fecha anterior; después de esa fecha, la misma solicitud es un error. En el WebSocket de eventos, una conexión así se rechaza con 403 PERMISSION_REQUIRED. Envía x-auth-org con el UUID de la organización en la que quieres actuar (Dirigir una llamada a una organización cliente).

Registra cada respuesta que incluya Deprecation, con la operación y la fecha de Sunset, para encontrar estas llamadas antes de esa fecha.

Cambios sin nueva versión

Estos cambios pueden aparecer en la API existente en cualquier momento; los más relevantes se anuncian en el registro de cambios:

• Operaciones nuevas.
• Campos opcionales nuevos en las solicitudes.
• Campos nuevos en las respuestas.
• Valores nuevos en los enums, como un nuevo tipo de alerta o de evento.

Escribe clientes que los toleren:

• Ignora los campos de respuesta que no usas y no falles con los que no reconoces. La mayoría de las bibliotecas JSON lo hacen por defecto; los deserializadores estrictos (por ejemplo Jackson con FAIL_ON_UNKNOWN_PROPERTIES) necesitan desactivarlo.
• Maneja los valores de enum que no conoces, por ejemplo registrándolos y omitiendo el elemento, en lugar de lanzar una excepción.
• Trata un campo ausente como nulo. Los campos con valor nulo se omiten en las respuestas.
• No dependas del orden de los campos de una respuesta ni de los elementos de una lista, salvo que la operación documente un orden.

Mantente informado

• El registro de cambios lista los cambios relevantes y tiene un feed RSS.
• El info.version de la especificación OpenAPI no cambia entre versiones. Para ver exactamente qué cambió, guarda una copia de la especificación y compárala con la actual.