Skip to content

Changes

Page history
Mise à jour de Points de terminaison API BaLex authored by Lucie Bader's avatar Lucie Bader
Show whitespace changes
Inline Side-by-side
Documentation/Fonctionnement-de-l'extension/Points-de-terminaison-API-BaLex.md
View page @ 24e5b3d7
****Consultation Balex depuis Sélection****
# Fonctions
Les fonctions présentées ci-après sont définies dans les scripts [api.js](https://gitlab.liris.cnrs.fr/lex-game/balex2ff/-/blob/main/src/utils/api.js) et [definitions.js](https://gitlab.liris.cnrs.fr/lex-game/balex2ff/-/blob/main/src/utils/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, `data`est 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 `authToken`et `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>) [<id>].
#### `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`
- **Ajout automatique d'un mot dans le(s) lexique(s) de l'utilisateur** :
**Pour vérifier si le mot est dans le lexique personnel**
Après capture de la sélection et identification de la langue utilisateur
On récupère les lexiques PERSONNELS de l’utilisateur et on identifie l’id du lexique dont on veut extraire les graphies avec `https://babalex.lezinter.net/api/user/lexicons`
ex. [ { "id": 483, "language": "fr", "category": "User", "group": null, "comments": null, "discussion": null, "user": [] } ]
On vérifie si le mot sélectionné est dans le lexique avec soit :
- `https://babalex.lezinter.net/api/lexicon/extract/0?lexiconId=483` (renvoie une réponse de type [ "raquette", "chat", "science" ])
- https://babalex.lezinter.net/api/lexicon/entries/483 (renvoie une réponse de type [ { "id": 431, "graphy": "chat" }, { "id": 424, "graphy": "raquette" }, { "id": 430, "graphy": "science" } ])
**Pour afficher dans quels lexiques le mot est présent**
Récupérer les lexiques de l’utilisateur à partir de l’id utilisateur et de la langue `https://babalex.lezinter.net/api/lexicon/search?user_id=52&language=fr` (ici compte test)
Exemple de réponse : [ { "id": 483, "language": "fr", "category": "User", "group": null, "comments": null, "discussion": null, "user": { "id": 52, "pseudo": "test" } }, { "id": 486, "language": "fr", "category": "Group", "group": { "id": 19, "name": "Groupe1", "language": "fr", "description": "Test" }, "comments": null, "discussion": null, "user": null } ]
Ensuite on va vérifier si le mot sélectionné est dans un des lexiques (ici 483 ou 486)
Vérifier les graphies du lexique 483 et 486 avec `https://babalex.lezinter.net/api/lexicon/entries/lexiconId`
**Pour obtenir une définition**
Pour obtenir la définition ou les définitions possibles contenues dans le lexique de cet utilisateur (de groupe ou personnel)
Cas où l’utilisateur est connecté :
Méthode 1:
- `/api/entry/search` on regarde dans les lexiques de l’utilisateur en précisant la langue et la graphie en paramètres
Il faut identifier si on a un lexique de l'utilisateur présent dans la réponse sinon renvoyer un message pour dire que le mot n'est pas présent dans un de ses lexiques
Méthode 2 :
Récupérer les lexiques de l’utilisateur à partir de l’id utilisateur et de la langue `https://babalex.lezinter.net/api/lexicon/search?user_id=52&language=fr`
Obtenir une liste des graphies et leurs id à partir d’un id du lexique (donc ici 483 et 486)
On compare si on a une graphie qui correspond au mot sélectionné comme on l’a fait précédemment pour vérifier dans quels lexiques le mot est présent.
Utiliser `https://babalex.lezinter.net/api/entry/get/entryId`
TODO :
Cas où l’utilisateur n’est pas connecté :
- `/api/wiktionary/search` : on demande des définitions au Wiktionnaire avec les paramètres “language” et “graphy”
Cas où le mot n’est pas présent dans le lexique utilisateur :
**Surlignage des mots présents**
Après identification de la langue utilisateur :
- `/api/user/lexicons` : Récupérer la liste des lexiques de l’utilisateur
- Identifier celui dont la langue nous intéresse, par exemple id du lexique français fr = 425
- `/api/lexicon/entries/{id}`: Récupérer les entrées lexicales à partir de l’id
Il faudrait cibler un lexique en particulier ex. lexique personnel ou lexique 1…
**Ajout manuel d’un mot au lexique de l’utilisateur**
Après identification de la langue et capture de la sélection de l’utilisateur.
Il faut identifier dans quel lexique l’utilisateur souhaite ajouter le mot.
Lorsque l’utilisateur clique sur un pictogramme représentant un lexique, on doit pouvoir récupérer son id puis récupérer les entrées lexicales présentes dans ce lexiques
- `/api/wiktionary/search` : Pour chercher des informations sur ce mot dans le wiktionnaire
- `/api/entry/search` : On peut vérifier si le mot existe déjà dans un autre lexique avec
- `/api/entry/copy` : Puis recopier l’entrée lexicale (pour identifier le mot voir [stratégie](#9))
- `/api/entry/create` : Si le mot n’existe pas dans aucun lexique, ni dans le wiktionnaire,il sera ajouté dans le lexique des nouveaux mots.
**Ajout automatique d’un mot au lexique de l’utilisateur**
On doit avoir accès au lexique personnel et récupérer ses entrées lexicales.
- `/api/wiktionary/search` : Il faudrait vérifier si le mot existe dans le wiktionnaire pour filtrer les mots en ne prenant que ceux standards
On compare avec les entrées présentes dans le lexique personnel et on l’ajoute automatiquement s’il n’est pas présent.
**Connexion**
Cas avec les credentials stockés :
- `/api/user/details` : L'extension interroge l'API pour vérifier si une session valide existe
- `/api/user/lexicons` : Si une session valide existe, charger les données de l'utilisateur (lexiques)