Sources : APIs et intégrations

Les outils de la station : les APIs du tenant, et le catalogue que la recherche interroge.

Les APIs

apis:
  - name: cuisine
    openapi_url: https://api.teranga.example.sn/openapi.json
    base_url: https://api.teranga.example.sn
    auth: {type: api_key, key_name: X-API-Key, key_location: header, key_env: TERANGA_KEY}
    operations:
      - {id: getMenu,            access: read}
      - {id: getDeliveryOptions, access: read}
      - {id: checkDeliverable,   access: read}
      - {id: getDeliveryPrice,   access: read}
      - {id: placeOrder,         access: write}
      - {id: createDelivery,     access: write, reversible: false}
      - {id: deleteCustomer,     access: write, exposed: false}

• operations est une liste blanche. Une opération qui n'y figure pas n'est pas joignable, même si l'OpenAPI la décrit. La liste est obligatoire et jamais vide. Ne listez pas une écriture que rien n'utilise, sauf en exposed: false pour la documenter.

attribut	effet
id	l'operationId de l'OpenAPI. Une même opération déclarée deux fois est refusée.
access	obligatoire. read ne change rien chez le tenant et s'exécute tout de suite. write change quelque chose et est réservée : seuls un submit, la garde de submit (submit_guard.validate) ou la connexion (envoyer et vérifier un code) l'appellent. Déclaré, jamais deviné du verbe HTTP : une recherche est souvent un POST.
reversible	sur une écriture seulement : l'opération de la même API qui l'annule, ou false. false sur une opération qu'appelle un submit : la porte MCP annonce le submit comme destructif. Rien d'autre ne le lit encore.
exposed: false	listée, vérifiée contre l'OpenAPI au provisionnement, mais jamais joignable. La nommer ailleurs est refusé.

• Core refuse les contradictions au chargement. Une écriture appelée tout de suite (par l'invoke d'une skill, une garde check ou update) changerait le dossier du tenant sans submit ni personne pour confirmer. Un submit qui passe par une lecture ne dépose rien, et le reçu dirait le contraire.
• La clé ne figure jamais dans le fichier. key_env nomme une variable d'environnement. Le modèle ne la voit pas et ne l'envoie pas : il ne peut donc pas élargir ce qu'elle autorise.
• Séparez lectures et écritures en deux entrées quand le tenant a deux clés, ou simplement pour que la frontière se voie dans la config :

apis:
  - name: rh-lecture
    operations:
      - {id: getTimesheets,     access: read}
      - {id: getOvertimeReport, access: read}
    auth: {type: api_key, key_name: X-RH-Key, key_location: header, key_env: RH_READ_KEY}
    # …
  - name: rh-ecriture
    operations:
      - {id: approveTimesheets, access: write}
    auth: {type: api_key, key_name: X-RH-Key, key_location: header, key_env: RH_WRITE_KEY}
    # …

Une seule identité par clé

Aujourd'hui, la clé d'une API est celle de la station : tout le monde parle au tenant sous la même identité. Deux managers qui utilisent la même station sont, pour l'outil RH, le même manager. L'identité par personne arrive avec la version cible (on_behalf_of: identity).

Le catalogue

catalog:
  from_skill: takeMealSelection    # la skill à kinds qui renvoie tout le catalogue
  mode: live                       # live | indexed

• live : chaque recherche interroge la recherche du tenant (sous le paramètre query_arg), et montre ses résultats dans son ordre. Toujours à jour, sans index.
• indexed : le catalogue est lu une fois et indexé, puis relu quand la station est provisionnée ou resynchronisée ; rien ne surveille la source. Recherche sémantique ; la skill doit renvoyer tout le catalogue, sans pagination.