Pasar a la dirección de la API

Las integraciones anteriores llaman a la API en la dirección principal de Sursa, la que las personas abren en el navegador, por ejemplo https://app.sursa.com/v1/…. Ahora la API también tiene su propia dirección: https://api.sursa.com en la nube o https://api.<your domain> en su instalación. Está pensada para las integraciones: escala horizontalmente detrás de un balanceador de carga y no sirve nada más que la API.

No está obligado a cambiar. La dirección principal sigue sirviendo /v1 para las integraciones existentes, sin fecha de fin y sin redirección. Cambie cuando le convenga, para aprovechar las ventajas de la dirección de la API, y úsela en todas las integraciones nuevas.

Lo que se mantiene

Las rutas, los parámetros, los campos, los códigos de error y los eventos: GET /v1/cards es la misma solicitud en las dos direcciones.
Las claves de API. Las mismas claves kb_ y kbsrc_ funcionan en las dos direcciones, con el mismo rol, los mismos ámbitos y el mismo perfil de datos.
Las claves de idempotencia, los límites de frecuencia y las cuotas. Las solicitudes en las dos direcciones cuentan para las mismas cuotas de la organización.
Los webhooks. Las entregas, las firmas y los secretos no dependen de la dirección a la que llame.
Los enlaces de las respuestas. doc_url de un error apunta a este portal, y el encabezado Link de una página de una lista apunta a la dirección de la API, sea cual sea la dirección a la que llame.

Lo que cambia en la dirección de la API

En la dirección principal	En la dirección de la API
Todos los endpoints de la aplicación web, incluidos los internos	Solo los endpoints de la referencia pública de la API. Cualquier otra ruta responde `404` con el código `api.not_found`.
Una clave en `X-API-Key` o `Authorization`, o una cookie de sesión del navegador	Una clave o un token de acceso OAuth, preferiblemente en `Authorization: Bearer`. Las cookies se ignoran.
`GET /auth/me`	`GET /v1/me`. Las rutas de `/auth/` no se sirven.
El modo «View as» (ver la base como la ve un perfil de datos) mediante cookie	El encabezado `X-View-As`, para las claves con el rol `admin`.
Un servidor o un conjunto fijo de servidores	Varios servidores detrás de un balanceador de carga.

La última fila solo importa en un caso: la respuesta del asistente que transmite POST /v1/chat. Un flujo interrumpido continúa desde Last-Event-ID solo en el servidor que escribe la respuesta. Si su integración reanuda flujos, asigne a cada pregunta un request_id, para que un reintento en otro servidor reciba la respuesta guardada en lugar de una segunda respuesta. Consulte Reanudar un flujo interrumpido.

Antes de cambiar

Compruebe que todas las llamadas son públicas. Enumere las rutas a las que llama su integración y busque cada una en la referencia de la API, o compárelas con la especificación de la dirección nueva:

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

Una ruta que no figura en la referencia pública pertenece a la aplicación web. Sigue funcionando en la dirección principal, pero no se sirve en la dirección de la API, y su forma no es un compromiso público. Sustitúyala por un endpoint público, o mantenga esa parte de la integración en la dirección principal y comunique a su contacto en Sursa lo que necesita.

Compruebe cómo se autentica. Si la integración inicia sesión con la contraseña de un usuario y una cookie de sesión, pásela primero a una clave de API. Si envía X-API-Key, se recomienda cambiar a Authorization: Bearer, pero no es obligatorio.

Compruebe su red. Permita el HTTPS saliente hacia el nuevo nombre de host en su firewall y en sus proxies.

Cambiar paso a paso

Convierta la URL base en un ajuste de su integración, si todavía no lo es.

Pruebe la dirección nueva con una solicitud de lectura:

curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"

Ejecute el conjunto de pruebas de su integración contra la dirección nueva, con una clave de prueba y una colección de prueba.
Cambie una parte del tráfico, por ejemplo un proceso de trabajo o un entorno, y vigile en sus registros los 404 api.not_found, los 401 y los 5xx. Cada respuesta lleva X-Request-Id; guárdelo con sus registros.
Cambie el resto. Mantenga durante un tiempo la URL base anterior en su configuración para poder volver atrás en segundos.

Qué comprobar después del cambio

GET /v1/health en la dirección nueva devuelve la misma version que en la anterior.
Las respuestas incluyen los encabezados RateLimit. Si su integración reduce su ritmo según X-RateLimit-*, puede seguir haciéndolo: se envían los dos conjuntos. Consulte Límites de frecuencia y cuotas.
Si su integración funciona en un navegador, ya no necesita su propio proxy para CORS: la dirección de la API admite solicitudes desde cualquier origen, sin cookies.