Dirección de la API y entornos

La API de Sursa tiene su propia dirección, distinta de la que usan las personas para abrir Sursa en el navegador. Todas las rutas empiezan por /v1.

Dónde funciona Sursa	Dirección de la API	Este portal
Nube de Sursa	`https://api.sursa.com`	`https://developers.sursa.com`
Su propia instalación	`https://api.<your domain>`, según la configure su administrador	`/developers/` en la dirección de la API
Su instalación sin una dirección de la API aparte	la dirección principal de la instalación	`/developers/` en la dirección principal

La dirección de la API solo sirve la API: no tiene página de inicio de sesión, ni cookies, ni interfaz web. Cada solicitud se autentica con una clave de API o con un token de acceso OAuth. La dirección puede estar servida por varios servidores detrás de un balanceador de carga; su integración no necesita saber cuántos hay.

Las integraciones que llaman a la API en la dirección principal (por ejemplo, https://app.sursa.com/v1) siguen funcionando. Consulte Pasar a la dirección de la API para conocer las pocas diferencias y el cambio paso a paso.

URL base

Construya cada solicitud a partir de una única URL base de su configuración, para que el mismo código funcione con cualquier entorno:

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

Use solo HTTPS y mantenga la clave fuera de los registros de las solicitudes que haga.

Versión y especificación

GET /v1/health indica si la dirección está activa y devuelve la versión de Sursa que la sirve. Responde sin clave, así que puede usarlo en la supervisión:

curl https://api.sursa.com/v1/health

{"ok": true, "version": "v1.4.0"}

Es la versión de Sursa, no la de la API. La versión de la API es info.version de su especificación. La especificación OpenAPI 3.1 de la API se publica en la misma dirección, sin autenticación:

Ruta	Contenido
`GET /openapi.json`	La especificación pública, con esta dirección en `servers`.
`GET /v1/openapi-public.json`	La misma especificación. Admite `ETag` y `If-None-Match`.

Úsela para generar un cliente, para importar la API en una herramienta como Postman o para comprobar en el CI que su integración solo usa operaciones de la versión que espera. La referencia de la API de este portal se construye a partir del mismo archivo.

Pruebas

Sursa no tiene un modo de prueba aparte: cada solicitud con una clave actúa sobre los datos reales de su organización. Para desarrollar y probar sin riesgo:

Cree una clave aparte para el desarrollo con el rol y los ámbitos más restringidos que necesite el trabajo.
Escriba en una colección dedicada, por ejemplo sandbox, que solo pueda ver su equipo, y elimínela cuando termine.
Si su empresa tiene una organización o una instalación de Sursa aparte para pruebas, apunte a ella la URL base y la clave. No cambia nada más en su código.
Haga que los reintentos sean seguros desde el principio: envíe una Idempotency-Key con cada POST y PATCH.

La consola Probar de cada página de endpoint de la referencia de la API envía solicitudes reales con una clave que usted pega en ella. La clave se queda en la memoria de la pestaña del navegador y solo se envía a la dirección de la API.

Requisitos de red

HTTPS saliente (puerto 443) desde sus servidores hacia la dirección de la API.
En las reglas del firewall, permita el nombre de host en lugar de direcciones IP fijas, si su red lo permite: los servidores que hay detrás de la dirección pueden cambiar a medida que se añade capacidad.
Las aplicaciones de navegador pueden llamar a la API directamente: las respuestas admiten cualquier origen (Access-Control-Allow-Origin: *) sin cookies. Tenga en cuenta que una clave usada en un navegador la ve el usuario de ese navegador.