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.
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/statusL'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. |
| 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. |
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.