Ihre erste API-Anfrage

Verbindung vorbereiten#

Wählen Sie in Squario den Arbeitsbereich und öffnen Sie Einstellungen → API → Schlüssel. API-Zugriff erfordert einen geeigneten Tarif und die Berechtigung api.access. Eigentümer und Administratoren haben diese standardmäßig.

• Erstellen Sie einen benannten Schlüssel mit Ablaufdatum und nur dem Zugriff und den Ressourcen, die Ihre Integration benötigt.
• Kopieren Sie das Geheimnis, wenn es angezeigt wird. Später ist es nicht erneut abrufbar.
• Kopieren Sie die Basis-URL aus den Verbindungsdetails. Behalten Sie den /v1-Suffix.
• Bewahren Sie den Schlüssel im Secret Manager oder in der Serverumgebung auf. Beginnen Sie mit einem Leseschlüssel.

read -r -p 'API base URL from Settings → API: ' SQUARIO_API_BASE
SQUARIO_API_BASE="${SQUARIO_API_BASE%/}"
read -r -s -p 'API key: ' SQUARIO_API_KEY
printf '\n'
export SQUARIO_API_BASE SQUARIO_API_KEY

Identität überprüfen#

Diese Beispiele verwenden SQUARIO_API_BASE für die kopierte Basis-URL und SQUARIO_API_KEY für das Geheimnis. Setzen Sie beide in Ihrer lokalen Umgebung. /me liefert Schlüsselmetadaten, Arbeitsbereich und Mitglied sowie aktuelle Kontingent- und Rateninformationen. Das Geheimnis wird nie zurückgegeben.

curl --fail-with-body "$SQUARIO_API_BASE/me" \
  --header "Authorization: Bearer $SQUARIO_API_KEY"

const base = process.env.SQUARIO_API_BASE?.replace(/\/$/, "");
const key = process.env.SQUARIO_API_KEY;
if (!base || !key) throw new Error("Set SQUARIO_API_BASE and SQUARIO_API_KEY");

const response = await fetch(`${base}/me`, {
  headers: { Authorization: `Bearer ${key}` },
  signal: AbortSignal.timeout(30_000),
});
const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.error.code}: ${body.error.message} (${body.error.request_id})`);
}
console.log(body.data);

import json
import os
from urllib.request import Request, urlopen

base = os.environ["SQUARIO_API_BASE"].rstrip("/")
key = os.environ["SQUARIO_API_KEY"]
request = Request(f"{base}/me", headers={"Authorization": f"Bearer {key}"})
with urlopen(request, timeout=30) as response:
    body = json.load(response)
print(body["data"])

Ressource und Schema finden#

/resources liefert Katalogeinträge mit key, label, read_only, searchable und requires_model_id. Der Katalog wird nach den zugelassenen Ressourcen des Schlüssels gefiltert; Ressourcenberechtigungen werden beim Datenzugriff weiterhin geprüft. Beschreiben Sie eine Ressource, bevor Sie sich auf Felder verlassen oder Datensätze schreiben.

curl --fail-with-body "$SQUARIO_API_BASE/resources" \
  --header "Authorization: Bearer $SQUARIO_API_KEY"

curl --fail-with-body "$SQUARIO_API_BASE/resources/companies" \
  --header "Authorization: Bearer $SQUARIO_API_KEY"

Vertrag ohne Schlüssel prüfen#

Die Versionswurzel und /openapi.json sind öffentlich. Damit identifizieren Sie die API und laden ihren OpenAPI-3.1-Vertrag. Diese Aufrufe verbrauchen kein Anfragekontingent. Die Kopie dieser Dokumentation ist ein Release-Snapshot; das Dokument der bereitgestellten API entspricht deren Stand.

curl --fail-with-body "$SQUARIO_API_BASE"
curl --fail-with-body "$SQUARIO_API_BASE/openapi.json"

Integration zuverlässig gestalten#

Lesen Sie weiter zu Filtern und Paginierung für Lesezugriffe oder sicheren Änderungen für Erstellung und Aktualisierung. Lesen Sie die Fehleranleitung, bevor Sie Wiederholungen hinzufügen. Verwenden Sie Idempotency-Key für Schreibwiederholungen und beachten Sie Retry-After.