API-Adresse und Umgebungen
Die Sursa-API hat eine eigene Adresse, getrennt von der Adresse, unter der Menschen Sursa im Browser öffnen. Alle Pfade
beginnen mit /v1.
| Wo Sursa läuft | API-Adresse | Dieses Portal |
|---|---|---|
| Sursa-Cloud | https://api.sursa.com | https://developers.sursa.com |
| Ihre eigene Installation | https://api.<your domain>, wie von Ihrer Administration eingerichtet | /developers/ unter der API-Adresse |
| Ihre Installation ohne eigene API-Adresse | die Hauptadresse der Installation | /developers/ unter der Hauptadresse |
Die API-Adresse liefert nur die API aus: Dort gibt es keine Anmeldeseite, keine Cookies und keine Weboberfläche. Jede Anfrage wird mit einem API-Schlüssel oder einem OAuth-Zugriffstoken authentifiziert. Hinter der Adresse können mehrere Server mit einem Load Balancer stehen; Ihre Integration muss nicht wissen, wie viele es sind.
Integrationen, die die API unter der Hauptadresse aufrufen (zum Beispiel https://app.sursa.com/v1), funktionieren
weiter. Die wenigen Unterschiede und einen Umstieg Schritt für Schritt beschreibt
Umstieg auf die API-Adresse.
Basis-URL
Bauen Sie jede Anfrage aus einer einzigen Basis-URL in Ihrer Konfiguration auf, damit derselbe Code in jeder Umgebung läuft:
export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"
Verwenden Sie ausschließlich HTTPS und halten Sie den Schlüssel aus den Protokollen Ihrer Anfragen heraus.
Version und Spezifikation
GET /v1/health zeigt, ob die Adresse erreichbar ist, und gibt die Version von Sursa
zurück, die unter ihr läuft. Die Anfrage antwortet ohne Schlüssel, sodass Sie sie im Monitoring verwenden können:
curl https://api.sursa.com/v1/health{"ok": true, "version": "v1.4.0"}
Das ist die Version des Sursa-Release, nicht die der API. Die Version der API ist info.version ihrer Spezifikation.
Die OpenAPI-3.1-Spezifikation der API ist unter derselben Adresse ohne Authentifizierung veröffentlicht:
| Pfad | Inhalt |
|---|---|
GET /openapi.json | Die öffentliche Spezifikation, mit dieser Adresse in servers. |
GET /v1/openapi-public.json | Dieselbe Spezifikation. Unterstützt ETag und If-None-Match. |
Verwenden Sie sie, um einen Client zu generieren, um die API in ein Werkzeug wie Postman zu importieren oder um in der CI zu prüfen, dass Ihre Integration nur Operationen der erwarteten Version verwendet. Die API-Referenz dieses Portals wird aus derselben Datei erzeugt.
Testen
Sursa hat keinen separaten Testmodus: Jede Anfrage mit einem Schlüssel wirkt auf die echten Daten seiner Organisation. So entwickeln und testen Sie gefahrlos:
- Erstellen Sie für die Entwicklung einen eigenen Schlüssel mit der engsten Rolle und den engsten Scopes, die die Arbeit erfordert.
- Schreiben Sie in eine eigene Sammlung, zum Beispiel
sandbox, die nur Ihr Team sehen kann, und löschen Sie sie, wenn Sie fertig sind. - Hat Ihr Unternehmen eine separate Sursa-Organisation oder -Installation zum Testen, richten Sie Basis-URL und Schlüssel darauf aus. Sonst ändert sich nichts an Ihrem Code.
- Machen Sie Wiederholungen von Anfang an sicher: Senden Sie bei jedem
POSTundPATCHeinen Idempotency-Key.
Die Konsole Ausprobieren auf jeder Endpunktseite der API-Referenz sendet echte Anfragen mit einem Schlüssel, den Sie dort einfügen. Der Schlüssel bleibt im Speicher des Browser-Tabs und wird nur an die API-Adresse gesendet.
Netzwerkanforderungen
- Ausgehendes HTTPS (Port 443) von Ihren Servern zur API-Adresse.
- Geben Sie in Firewall-Regeln nach Möglichkeit den Hostnamen frei statt fester IP-Adressen: Die Server hinter der Adresse können sich ändern, wenn Kapazität hinzukommt.
- Browseranwendungen können die API direkt aufrufen: Antworten erlauben jeden Ursprung
(
Access-Control-Allow-Origin: *) ohne Cookies. Beachten Sie, dass ein Schlüssel, der im Browser verwendet wird, für die Person an diesem Browser sichtbar ist.