Adreça de l’API i entorns

L’API de Sursa té la seva pròpia adreça, separada de l’adreça que fan servir les persones per obrir Sursa al navegador. Tots els camins comencen per /v1.

On s’executa Sursa	Adreça de l’API	Aquest portal
Núvol de Sursa	`https://api.sursa.com`	`https://developers.sursa.com`
La vostra pròpia instal·lació	`https://api.<your domain>`, tal com l’hagi configurada qui administra la instal·lació	`/developers/` a l’adreça de l’API
La vostra instal·lació sense una adreça de l’API separada	l’adreça principal de la instal·lació	`/developers/` a l’adreça principal

L’adreça de l’API només serveix l’API: no hi ha pàgina d’inici de sessió, ni galetes, ni interfície web. Cada sol·licitud s’autentica amb una clau d’API o amb un token d’accés OAuth. L’adreça la poden servir diversos servidors darrere d’un balancejador de càrrega; la vostra integració no necessita saber quants n’hi ha.

Les integracions que criden l’API a l’adreça principal (per exemple, https://app.sursa.com/v1) continuen funcionant. A Passar a l’adreça de l’API trobareu les poques diferències i el canvi pas a pas.

URL base

Construïu cada sol·licitud a partir d’una sola URL base de la vostra configuració, perquè el mateix codi funcioni amb qualsevol entorn:

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

Feu servir només HTTPS i manteniu la clau fora dels registres de les sol·licituds que feu.

Versió i especificació

GET /v1/health indica si l’adreça funciona i retorna la versió de Sursa que la serveix. Respon sense clau, de manera que el podeu fer servir en el monitoratge:

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

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

Aquesta és la versió de la publicació de Sursa, no de l’API. La versió de l’API és el info.version de la seva especificació. L’especificació OpenAPI 3.1 de l’API es publica a la mateixa adreça, sense autenticació:

Camí	Contingut
`GET /openapi.json`	L’especificació pública, amb aquesta adreça a `servers`.
`GET /v1/openapi-public.json`	La mateixa especificació. Admet `ETag` i `If-None-Match`.

Feu-la servir per generar un client, per importar l’API en una eina com Postman o per comprovar a la CI que la vostra integració només fa servir operacions de la versió que espereu. La referència de l’API d’aquest portal es genera a partir del mateix fitxer.

Proves

Sursa no té un mode de prova separat: cada sol·licitud amb una clau actua sobre les dades reals de la seva organització. Per desenvolupar i provar sense risc:

Creeu una clau separada per al desenvolupament amb el rol i els àmbits mínims que necessiti la feina.
Escriviu en una col·lecció dedicada, per exemple sandbox, que només pugui veure el vostre equip, i elimineu-la quan acabeu.
Si la vostra empresa té una organització o una instal·lació de Sursa separada per a proves, apunteu-hi la URL base i la clau. No canvia res més del vostre codi.
Feu que els reintents siguin segurs des del principi: envieu una Idempotency-Key amb cada POST i PATCH.

La consola Provar de cada pàgina de punt final de la referència de l’API envia sol·licituds reals amb una clau que hi enganxeu. La clau es queda a la memòria de la pestanya del navegador i només s’envia a l’adreça de l’API.

Requisits de xarxa

HTTPS de sortida (port 443) des dels vostres servidors cap a l’adreça de l’API.
A les regles del tallafoc, permeteu el nom d’amfitrió en lloc d’adreces IP fixes, si la vostra xarxa ho permet: els servidors que hi ha darrere de l’adreça poden canviar a mesura que s’hi afegeix capacitat.
Les aplicacions de navegador poden cridar l’API directament: les respostes permeten qualsevol origen (Access-Control-Allow-Origin: *) sense galetes. Tingueu en compte que una clau que es fa servir en un navegador la pot veure qui fa servir aquell navegador.