Accès API

Chaque objet déclaré dans l'artefact est exposé via une API REST générée. Les mêmes points de terminaison alimentent l'interface utilisateur, les intégrations et les scripts ETL des clients — il n'y a aucune « API d'intégration » distincte à maintenir.

URL de base

https://<project-domain>/api/v1

Surfaces notables :

Le préfixe est /api/v1 par défaut (le basePath de l'API /api plus la version v1) et il est configurable sur la stack ObjectOS.

Contrôler ce qui est exposé

L'exposition de l'API est gouvernée par objet dans l'artefact, et non au niveau de la passerelle :

• Définissez apiEnabled: false sur un objet pour le garder entièrement hors de la surface REST (ses routes renvoient 404).
• Définissez une liste blanche apiMethods (par ex. ['get', 'list']) pour rendre un objet en lecture seule ou restreindre autrement les opérations accessibles.

Les deux sont appliqués au niveau de la couche REST — voir API REST → Restreindre la surface d'API.

Options d'authentification

Les appelants peuvent s'authentifier de trois façons :

Les trois passent par le même AuthPlugin et se résolvent en un contexte sys_user que le SecurityPlugin évalue par rapport aux permissions et à l'accès aux enregistrements.

Clés API

Les clés API sont des enregistrements sys_api_key de première classe. La valeur de la clé elle-même est stockée hachée — seuls le prefix et les métadonnées restent interrogeables, de sorte qu'une clé divulguée ne peut pas être reconstituée à partir de la base de données.

Émettez une clé de deux façons :

• Console — connectez-vous à Console → API Keys en tant qu'administrateur, choisissez l'utilisateur propriétaire, définissez éventuellement une date d'expiration et copiez le secret affiché une seule fois.

• Endpoint en libre-service — POST /api/v1/keys génère une clé pour l'appelant authentifié et renvoie le secret brut exactement une fois. La clé est rattachée au propre utilisateur de l'appelant et ne peut donc pas servir à usurper une autre identité :

  curl -X POST https://app.example.com/api/v1/keys \
    -H "Authorization: Bearer <session-or-access-token>" \
    -H "Content-Type: application/json" \
    -d '{"name": "etl-pipeline"}'
  # → { "id": "...", "name": "etl-pipeline", "prefix": "os_pk_…", "key": "os_pk_live_…" }

Passez la clé sur les requêtes suivantes comme jeton bearer, comme en-tête x-api-key ou comme Authorization: ApiKey. Les API REST de données et de métadonnées l'authentifient via le même vérificateur que MCP, sous les permissions et la sécurité au niveau des enregistrements du propriétaire de la clé :

curl https://app.example.com/api/v1/data/account \
  -H "x-api-key: os_pk_live_…"

Pour révoquer une clé, exécutez l'action revoke_api_key sur l'enregistrement sys_api_key correspondant (également disponible dans l'interface de la Console). La révocation prend effet immédiatement lors de la requête suivante.

Pagination, filtrage et tri

Les points de terminaison de liste générés acceptent les paramètres de requête ObjectStack standard :

Reportez-vous à la documentation du framework pour la grammaire de filtre complète — la grammaire d'exécution fait foi.

Limitation de débit

Utilisez la primitive RateLimiter du framework (ou votre ingress / API gateway) pour appliquer des limites par IP et par identité. Les compartiments de départ recommandés sont documentés dans Préparation à la production.

CORS

Si les appelants s'exécutent dans un navigateur sur une origine différente, configurez CORS au niveau de l'ingress ou via le middleware du runtime. Ne combinez pas les origines génériques avec des requêtes avec identifiants.

OpenAPI / découverte

Le runtime peut servir un document OpenAPI pour l'API REST générée lorsque la capacité correspondante est incluse dans l'image. Les intégrations clients devraient générer leurs clients à partir du document OpenAPI propre à chaque déploiement plutôt que de construire les URL à la main, car les noms d'objets et les routes générées suivent l'artefact déployé.