Wiki · Aller plus loin

L'API locale

Piloter TurboTexte depuis vos propres scripts, en HTTP sur votre machine.

À quoi ça sert

TurboTexte expose une petite API HTTP sur votre propre machine. Elle permet de faire depuis un script ce que vous feriez à la main dans la fenêtre : créer des raccourcis en masse, exporter la liste, activer un groupe, ou suspendre la substitution le temps d'une tâche.

Deux usages reviennent souvent : générer des centaines de raccourcis à partir d'un tableur ou d'une base, et synchroniser sa liste entre plusieurs postes avec ses propres outils.

Quels abonnements y donnent droit

L'API locale est réservée aux offres Équipe et Entreprise. Ni la période d'essai ni les abonnements individuels ne l'ouvrent.

La raison est simple à dire : l'API donne accès par programme à tout ce que fait l'application, la grille d'abréviations comprise. C'est l'outil dont ont besoin les organisations qui déploient TurboTexte sur des dizaines de postes et qui alimentent leurs listes depuis leurs propres systèmes ; ce n'est pas un besoin de l'usage individuel.

Sur un abonnement qui n'y donne pas droit, le serveur ne démarre pas et l'onglet API des préférences le dit. Le reste de l'application fonctionne normalement.

Une panne de réseau ne retire jamais la fonction à qui l'a payée : l'application retient le droit d'une exécution à l'autre, comme elle retient la licence elle-même.

Adresse et sécurité

Le serveur n'écoute que sur l'interface locale :

http://127.0.0.1:8420/api/v1

« Interface locale » veut dire que seuls les programmes tournant sur votre ordinateur peuvent l'atteindre. Elle n'est accessible ni depuis votre réseau ni depuis Internet, même si votre pare-feu est grand ouvert.

Toutes les routes exigent un jeton d'authentification, sauf /ping. Le jeton se trouve dans les préférences de l'application, onglet API, où vous pouvez aussi changer le port, désactiver le serveur, et régénérer le jeton si vous pensez l'avoir laissé traîner.

Transmettez-le dans l'en-tête Authorization :

curl -H "Authorization: Bearer VOTRE_JETON" \
     http://127.0.0.1:8420/api/v1/status

L'en-tête X-TurboTexte-Token est également accepté. Le passage par la chaîne de requête fonctionne aussi, mais évitez-le : une URL se retrouve dans les journaux et dans l'historique du terminal.

Deux options en ligne de commande

--no-api démarre l'application sans le serveur, le temps d'une exécution. --api-port 9000 change le port sans toucher à votre préférence enregistrée. Les deux servent surtout aux tests.

Les raccourcis

Méthode	Chemin	Effet
GET	/combos	Lister, avec recherche, filtrage et pagination.
POST	/combos	Créer un raccourci.
DELETE	/combos	Supprimer plusieurs raccourcis d'un coup.
GET	/combos/{id}	Lire un raccourci, par identifiant ou par abréviation.
PATCH	/combos/{id}	Modifier les champs fournis.
DELETE	/combos/{id}	Supprimer un raccourci.
POST	/combos/{id}/duplicate	Dupliquer.
POST	/combos/{id}/preview	Évaluer le contenu sans l'insérer nulle part.
GET	/combos/export	Exporter en JSON, CSV ou aide-mémoire.
POST	/combos/import	Importer une liste.
POST	/combos/save	Forcer l'enregistrement sur le disque.
POST	/combos/reload	Recharger depuis le disque.

Les groupes

Méthode	Chemin	Effet
GET	/groups	Lister les groupes.
POST	/groups	Créer un groupe.
GET	/groups/{id}	Lire un groupe, par identifiant ou par nom.
PATCH	/groups/{id}	Modifier les champs fournis.
DELETE	/groups/{id}	Supprimer un groupe.
GET	/groups/{id}/combos	Lister les raccourcis du groupe.
POST	/groups/{id}/move	Déplacer le groupe dans la liste.
POST	/groups/sort	Trier les groupes par nom.
GET	/groups/categories	Les catégories acceptées, avec leur couleur.
POST	/groups/{id}/import-csv	Importer des raccourcis CSV dans le groupe.
GET	/groups/{id}/export-csv	Exporter le groupe en CSV.

L'application

Méthode	Chemin	Effet
GET	/ping	Vérifier que l'API répond. Seule route sans jeton.
GET	/status	État complet de l'application.
GET	/routes	Lister toutes les routes de l'API.
POST	/app/enable	Activer la substitution.
POST	/app/disable	Suspendre la substitution.
POST	/app/toggle	Basculer l'état.
POST	/app/show	Afficher la fenêtre principale.
POST	/app/picker	Ouvrir le sélecteur de raccourcis.
POST	/app/quit	Quitter proprement.
GET	/app/log	Lire les dernières lignes du journal.

Préférences, historique, sauvegardes

Méthode	Chemin	Effet
GET	/preferences	Lire toutes les préférences.
PATCH	/preferences	Modifier les préférences fournies.
POST	/preferences/reset	Rétablir les valeurs par défaut.
GET	/api-settings	Lire la configuration de l'API.
POST	/api-settings/token	Régénérer le jeton.
GET	/stats	Statistiques d'usage sur une période.
GET	/history	Lister les modifications enregistrées.
POST	/history/undo	Annuler la dernière modification.
POST	/history/redo	Rétablir.
GET	/backups	Lister les sauvegardes.
POST	/backups	Créer une sauvegarde.
POST	/backups/restore	Restaurer une sauvegarde.
POST	/text/expand	Développer un texte sans l'insérer.
GET	/text/matches	Lister les raccourcis correspondant à une saisie.
GET	/text/document-formats	Les formats de document acceptés.
POST	/text/expand-document	Développer un document entier dans une copie.
POST	/stats/erase	Effacer toutes les statistiques. Exige confirm.

Confidentialité, synchronisation, mise à jour

Méthode	Chemin	Effet
GET	/privacy	Les réglages de confidentialité.
PATCH	/privacy	Les modifier, et réaligner les statistiques déjà enregistrées.
GET	/sync	État et réglages de la synchronisation.
PATCH	/sync	Interrupteur, intervalle, tables exclues.
POST	/sync/now	Lancer un cycle immédiatement.
GET	/update	Version installée, version disponible, caractère obligatoire.
POST	/update/check	Déclencher une vérification de mise à jour.

Ce que l'API ne fera jamais

Trois choses sont exclues par principe, et le resteront. Elles ne sont pas oubliées : elles dépassent ce que vous pouvez annuler depuis l'application.

• Taper dans votre fenêtre active. /text/expand développe le texte que vous lui envoyez et vous rend le résultat ; ce que vous en faites vous regarde.
• Installer une mise à jour. L'installation quitte l'application et lance un installeur avec élévation de privilèges. Derrière un appel HTTP, ce serait une primitive dangereuse.
• Révéler un secret. Ni le jeton de licence, ni le jeton de l'API, ni l'identifiant de votre installation. /ping donne le chemin du fichier du jeton, jamais sa valeur.

Ce qui est destructif mais réversible reste accessible, à condition d'être demandé explicitement : /stats/erase exige "confirm": true, et /text/expand-document exige "overwrite": true pour remplacer un fichier existant. Le document d'origine, lui, n'est jamais écrasé.

Description machine

L'application sert elle-même une description OpenAPI 3.1 à l'adresse /api/v1/openapi.json, et une documentation détaillée à /api/v1/docs. Ces deux adresses font toujours foi : elles décrivent la version que vous avez installée, là où cette page décrit l'état général de l'API.

La description OpenAPI se charge dans la plupart des outils clients, ce qui permet de générer le code d'appel plutôt que de l'écrire à la main.

Un exemple complet

Créer un raccourci, puis vérifier qu'il est bien enregistré :

JETON="votre-jeton"
BASE="http://127.0.0.1:8420/api/v1"

curl -s -X POST "$BASE/combos" \
     -H "Authorization: Bearer $JETON" \
     -H "Content-Type: application/json" \
     -d '{"keyword":";;ml","snippet":"prenom.nom@exemple.fr"}'

curl -s "$BASE/combos/;;ml" -H "Authorization: Bearer $JETON"

Si le premier appel renvoie une erreur d'authentification, c'est le jeton qui est en cause. S'il ne répond pas du tout, vérifiez avec curl http://127.0.0.1:8420/api/v1/ping que le serveur est bien démarré et que le port correspond à celui des préférences.