Votre première requête API

Préparer la connexion#

Dans Squario, choisissez l’espace de travail et ouvrez Paramètres → API → Clés. L’accès nécessite une offre compatible et la permission api.access. Les propriétaires et administrateurs possèdent cette permission par défaut.

• Créez une clé nommée avec une expiration obligatoire et les accès et ressources strictement nécessaires à votre intégration.
• Copiez le secret lorsqu’il est affiché. Vous ne pourrez plus le consulter ensuite.
• Copiez l’URL de base indiquée dans les informations de connexion. Conservez son suffixe /v1.
• Conservez la clé dans le gestionnaire de secrets ou l’environnement de votre serveur. Commencez avec une clé en lecture seule.

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

Vérifier votre identité#

Ces exemples utilisent SQUARIO_API_BASE pour l’URL de base copiée et SQUARIO_API_KEY pour le secret. Définissez ces variables dans votre environnement local. /me renvoie les métadonnées de votre clé, l’espace de travail et le membre, ainsi que le quota et les limites de débit actuels. Le secret n’est jamais renvoyé.

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"])

Trouver une ressource et son schéma#

/resources renvoie les entrées du catalogue avec key, label, read_only, searchable et requires_model_id. Le catalogue est filtré selon les ressources autorisées par la clé ; les permissions sur les ressources restent vérifiées lors de l’accès aux données. Décrivez une ressource avant d’utiliser ses champs ou d’écrire des fiches.

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"

Consulter le contrat sans clé#

La racine de la version et /openapi.json sont publiques. Elles permettent d’identifier l’API et de récupérer son contrat OpenAPI 3.1. Ces appels ne consomment pas le quota de votre espace de travail. La copie présente dans cette documentation est un instantané de la version ; le document de l’API déployée reflète son déploiement.

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

Fiabiliser votre intégration#

Continuez avec les filtres et la pagination pour les lectures, ou les écritures sécurisées pour les créations et modifications. Lisez le guide des erreurs avant d’ajouter des tentatives automatiques. Utilisez Idempotency-Key pour réessayer une écriture et respectez Retry-After.