Skip to content
Snippets Groups Projects

Points de terminaison API BaLex

Last edited by Alissa Sounalath

Fonctions

Les fonctions présentées ci-après sont définies dans les scripts api.js et definitions.js.

callApi

Fonction utilitaire qui centralise l'exécution des requêtes vers l'API. Elle gère la configuration des entêtes, la méthode (GET/POST), le corps de la requête et le traitement de la réponse.
Paramètres d'entrée :

  • url (string) : l’adresse complète de l’API à appeler
  • authToken (string|null) : le token d’authentification, s’il existe, pour ajouter un header Authorization.
  • method (string, optionnel, par défaut 'GET') : la méthode HTTP à utiliser
  • data (object|null, optionnel) : un objet qui sera converti en JSON et envoyé dans le corps de la requête pour les méthodes qui en nécessitent

Données manipulées :
Les en-têtes nécessaires aux requêtes contiennent :
Content-Type: application/json
Authorization: Bearer <authToken>
Pour le corps de la requête, dataest transformé en JSON avec JSON.stringify(data) et assigné à fetchOptions.body.

Traitement de la réponse :
La fonction attend la réponse de fetch(url, fetchOptions). Si la réponse n'est pas ok, elle lève une exception avec un message d'erreur (code de statut + statut textuel). Sinon, elle retourne le résultat parsé en JSON avec await response.json(). La sortie attendue est donc un objet au format JSON représentant la réponse de l'API (ou exception si erreur).

getLexicons

Cette fonction récupère les lexiques (et les informations les concernant) de l'utilisateur. Le paramètre d'entrée est authToken pour autoriser la requête. La fonction appelle callApi en fournissant l'URL de la requête et le token.
Le point de terminaison utilisé est : api/lexicon/search
Les données récupérées sont :

[
  {
    "id": 0,
    "createdAt": "2025-02-20T09:15:21.491Z",
    "language": "string",
    "category": "string",
    "comments": "string",
    "discussion": "string",
    "user": {},
    "group": {}
  }
]

getLexiconsEntries

Cette fonction récupère les entrées d'un lexique spécifique. Elle attend en entrée authTokenet lexiconId qui est l'identifiant (id) du lexique dont on souhaite récupérer les entrées.
Le point de terminaison est : api/lexicon/entries/{lexiconId}
La sortie attendue est un tableau d'entrées pour le lexique spécifié. Chaque entrée a un id et une graphy.

getAllLexiconWords

Cette fonction récupère toutes les graphies de l'ensemble des lexiques de l'utilisateur. Elle utilise getLexicons puis itère sur chaque lexique avec getLexiconEntries pour obtenir les entrées. Les mots sont ensuite regroupés dans un objet dont les clés sont des libellés uniques. Pour un lexique de catégorie User, le libellé est construit comme : Lexique personnel (<pseudo de l'utilisateur | Inconnu>) [<id>]. Pour la catégorie Group, le libellé est : `Lexique de groupe (<nom du groupe | Inconnu>) [].

getWiktionaryDefinition

Cette fonction récupère la définition d'un mot depuis le Wiktionnaire. Le paramètre d'entrée est word (string). L'URL utilisée est : https://fr.wiktionary.org/w/api.php?action=query&format=json&origin=*&prop=extracts&exintro=true&titles=<word>
Cette fonction a été utilisée dans une première version de l'extension mais a été remplacée par une fonction utilisant l'API de BaLex.

AddWord

Cette fonction ajoute le mot sélectionné dans un ou plusieurs lexiques.
Paramètres d'entrée :

  • authToken
  • selectedWord (string)
  • lexiconIds (tableau de nombres) : liste des identifiants des lexiques dans lesquels le mot doit être ajouté.
  • force (boolean, optionnel, par défaut false) : Un flag pour forcer l’ajout. Si force = true, l'entrée est créée même si le mot n'est pas trouvé dans le Wiktionnaire, mais uniquement dans le lexique des nouveaux mots (cf. documentation API BaLex).

Données manipulées :
Le corps de la requête est un objet JSON constitué de :

  • graphy : le mot à ajouter
  • force
  • target_lex : le tableau des identifiants des lexiques cibles

Le point de terminaison est api/entry/create et la méthode est POST.

La sortie attendue est la réponse JSON de l'API après l'ajout du mot, ou bien une exception en cas d'erreur (absence de token d'authentification, mot vide, aucun lexique sélectionné).

fetchLexiconDefinitions

Cette fonction récupère les définitions d'un mot dans les lexiques de l'utilisateur. Après avoir récupéré les lexiques, la fonction effectue une requête pour rechercher le mot dans le lexique ciblé. Le point de terminaison utilisé est : api/entry/search et l'URL construite est : api/entry/search?graphy=<word>&language=<language>&target_lex=<lex.id>

Pour chaque entrée, elle vérifie si une propriété Sense?.Definitions existe, et si la propriété Def est présente.
La sortie attendue est un tableau d'objets : { source: <nom_du_lexique>, text: <texte_de_la_définition>, lexiconId: <id> }

wikiApiResponse

Cette fonction récupère les définitions du Wiktionnaire via l'API de BaLex plutôt qu'un appel direct au Wiktionnaire (fonction getWiktionaryDefinition précédente). Le point de terminaison utilisé est : api/wiktionary/search?graphy=<word>&language=fr. Les données JSON contenant les informations brutes du mot sont retournées par l'API.

Fonctionnalités

Ces requêtes à l'API de BaLex ont permis la mise en place des fonctionnalités suivantes :

  • Vérifier si le mot est présent dans le lexique de l'utilisateur : api/lexicon/search pour récupérer les identifiants des lexiques de l'utilisateur, puis api/lexicon/entries/{id} où id est le numéro d'identifiant du lexique.
  • Afficher dans quel(s) lexique(s) le mot est présent : api/lexicon/search pour récupérer les lexiques de l'utilisateur, puis recherche du mot dans chaque lexique grâce à api/entry/search?graphy=<word>&language=<language>&target_lex=<lex.id>. La fonction searchInLexicons permet ensuite de construire une map des lexiques où le mot a été trouvé
  • Obtenir une définition : Si l'utilisateur n'est pas connecté, il peut accéder à la définition issue du Wiktionnaire (sans passer par l'API de BaLex) via https://fr.wiktionary.org/w/api.php?action=query&format=json&origin=*&prop=extracts&exintro=true&titles=${encodeURIComponent(word)}. Si l'utilisateur est connecté, il a accès aux définitions issues de ses lexiques, et issues du Wiktionnaire via l'API de BaLex (api/wiktionary/search?graphy=<word>&language=fr).
  • Surlignage des mots présents dans le(s) lexique(s) : Chaque lexique récupéré via api/lexicon/search est interrogé pour obtenir ses entrées contenant les mots à surligner api/lexicon/entries/{lexiconId}.
  • Ajout manuel d'un mot dans le(s) lexique(s) de l'utilisateur : api/entry/create via la fonction AddWord (pour l'instant l'ajout d'un mot est disponible uniquement pour le français)
  • Ajout automatique d'un mot dans le(s) lexique(s) personnel(s) user de l'utilisateur : api/entry/create via la fonction autoAddWordaprès détection du dépassement de seuil défini (voir script pyodide_worker.js)