Changes

Enzo Simonnet · 3a3f423f
--- a/BaBaLex-API.md
+++ b/BaBaLex-API.md
-API BaBaLex Specification
+t
\ No newline at end of file
-Table des matières
- 1  Miscellaneous	1
- 1.1  search	1
- 1.2  completeShare	3
- 2  Entry	4
- 2.1  createEntry	4
- 2.2  supprEntry	5
- 2.3  editEntry	6
- 3  Graph	8
- 3.1  addGraph	8
- 3.2  supprGraph	9
- 3.3  extractGraph	10
- 3.4  importGraph	11
- 4  Label	12
- 4.1  addLabel	12
- 4.2  rmvLabel	13
- 4.3  supprLabel	15
- 4.4  setLabel	15
- 5  List	16
- 5.1  createList	16
- 5.2  supprList	17
- 6  Lexicon	18
- 6.1  createLex	18
- 6.2  supprLex	19
-Méthodes
- 1  Miscellaneous
- 1.1  search
-Rechercher un mot dans BaBaLex et afficher ses informations lexicales correspondant aux différents lexiques + wiktionnaire
-Lancé par : utilisateur (recherche de mot), système (création de flashcards)
-Use case :
-    • un utilisateur recherche un mot dans la barre de recherche (2.1)
-    • un utilisateur clique sur une graphie dans un lexique (3.9)
-    • Récupération automatique des informations lexicales pour les Flashcards
-Request
-Method
-URL            
-GET
-api/search/
-Type
-Params
-Values
-GET
-GET
-GET
-GET
-graphie
-langue
-user
-lexs_cibles
-string
-string
-user_id
-array<lexique>
-graphie
-forme écrite du mot
-langue
-language de la recherche
-user
-personne qui fait la requête
-lexs_cibles (optional. Default : all)
-spécifier dans quels lexiques la recherche est effectuée
-Response
-Status
-Response
-200
-La réponse est l’ensemble “fusionné” des entrées lexicales correspondant à la graphie (voir structure dans le wiki) :
-    1. Récupérer entrées lexicales dans les lexiques où la graphie est présente (potentiellement 0 résultat)
-    2. Chercher dans le Wiktionnaire
-	SI présent :
-		Récupérer informations lexicales 
-	SINON :
-		Renvoyer un statut de requête pour lancer procédure « msg d’erreur + entrée vide »
-500
-{"error":"Something went wrong. Please try again later."}
- 1.2  completeShare
-Transfère des entrées lexicales complètes (avec les labels publics et informations lexicales) d’un lexique à d’autres
-Use case : partage complet ( 3.5)
-Lancé par : utilisateur
-Request
-Method
-URL            
-POST
-api/completeShare/
-Type
-Params
-Values
-POST
-POST
-POST
-POST
-entrees
-lex_source
-lexs
-user
-array<graphie>
-lexique
-array<lexique>
-user_id
-lex_source
-lexique d’origine des entrées
-entrees
-Sélection des entrées souhaitées
-lexs
-Lexiques cibles
-Response
-Status
-Response
-200
-Nouvelles entrées lexicales dans les lexiques cibles.
-Si une entrée correspondant à la même graphie existe, proposer les 3 choix différents : overwrite, ne pas overwrite, fusionner
-Si c’est une opérattion utilisateur : historique des modifications mis à jour
-401
-{"error":"Invalid entrees."}
-401
-{"error":"Invalid lexs."}
-500
-{"error":"Something went wrong. Please try again later."}
- 2  Entry
- 2.1  createEntry
-Crée dans les lexiques sélectionnés une nouvelle entrée
-    • Utile pour importer une liste dans un lexique.
-    • Ajouter une entrée manuellement
-Use case : ci-dessus (3.2, 4.2)
-Lancé par : utilisateur
-Request
-Method
-URL            
-POST
-api/createEntry/
-Type
-Params
-Values
-POST
-POST
-POST
-graph
-lexs
-user
-array<graphie>
-array<lexiques>
-user_id
-lexs
-ensemble des graphies à constituer en entrée lexicale (peut être une liste, une sous-liste, un ensemble de graphies)
-lexs
-Lexiques cibles
-Response
-Status
-Response
-200
-Nouvelle entrée lexicale dans les lexiques cibles.
-Si c’est une opérattion utilisateur : historique des modifications mis à jour
-401
-{"error":"Invalid graphie."}
-401
-{"error":"Invalid lexs."}
-500
-{"error":"Something went wrong. Please try again later."}
- 2.2  supprEntry
-Supprime une entrée d’un lexique
-Use case : 3.4.3
-Lancé par : utilisateur
-Request
-Method
-URL            
-DELETE
-api/supprEntry/
-Type
-Params
-Values
-DELETE
-DELETE
-DELETE
-entree
-lex
-user
-entrée lexicale
-lexique
-user_id
-entree
-Entrée à supprimer
-lex
-Lexique de l’entrée
-Response
-Status
-Response
-200
-Entrée supprimée
-Si c’est une opérattion utilisateur : historique des modifications mis à jour
-401
-{"error":"Invalid entree."}
-500
-{"error":"Something went wrong. Please try again later."}
- 2.3  editEntry
-Modifie les informations lexicales d’une entrée
-Use case : 3.1
-Lancé par : utilisateur
-Request
-Method
-URL            
-POST
-api/editEntry/
-Type
-Params
-Values
-POST
-POST
-POST
-POST
-POST
-entree
-content
-comment
-user
-lex
-entrée lexicale
-data
-string
-user_id
-lexique
-entree
-Entrée à modifier
-content
-Contenu entré par l’utilisateur
-comment
-idem
-lex
-lexique où l’entrée est modifiée
-Response
-Status
-Response
-200
-Nouvelle version de l’entrée lexicale + historique des modifications mis à jour
-401
-{"error":"Invalid content."}
-500
-{"error":"Something went wrong. Please try again later."}
- 3  Graph
- 3.1  addGraph
-Ajoute dans les listes sélectionnés de nouvelles graphies
-Use case : 4.7
-Lancé par : utilisateur
-Request
-Method
-URL            
-POST
-api/addGraph/
-Type
-Params
-Values
-POST
-POST
-POST
-list
-graph
-user
-array<liste>
-array<graphie>
-user_id
-list
-Listes cibles
-Response
-Status
-Response
-200
-Nouvelles graphies dans les listes cibles.
-Si c’est une opérattion utilisateur : historique des modifications mis à jour
-401
-{"error":"Invalid graph."}
-401
-{"error":"Invalid list."}
-500
-{"error":"Something went wrong. Please try again later."}
- 3.2  supprGraph
-Supprime des graphies dans les listes sélectionnés
-Use case : 4.3.1
-Lancé par : utilisateur
-Request
-Method
-URL            
-DELETE
-api/supprGraph/
-Type
-Params
-Values
-DELETE
-DELETE
-DELETE
-list
-graph
-user
-array<liste>
-array<graphie>
-user_id
-list
-Listes cibles
-Response
-Status
-Response
-200
-Graphies supprimées
-Si c’est une opérattion utilisateur : historique des modifications mis à jour
-401
-{"error":"Invalid graphie."}
-401
-{"error":"Invalid list."}
-500
-{"error":"Something went wrong. Please try again later."}
- 3.3  extractGraph
-Récupère un nombre n de graphies d’une liste ou un lexique
-Permet de :
-    • créer des grilles MW
-    • importer des mots dans les jeux
-    • afficher les listes et lexiques
-    • extraire une liste d’un lexique 3.4.2
-    • faire un partage “safe” d’un lexique à un autre 3.5
-Use case : 4.7, 3.5, 3.4.2
-Lancé par : utilisateur
-Request
-Method
-URL            
-GET
-api/extractGraph/
-Type
-Params
-Values
-GET
-GET
-GET
-GET
-GET
-graphs
-n
-lexs
-lists
-user
-array<graphs>
-integer
-array<lexique>
-array<liste>
-user_id
-n (optionnal. Default : all)
-nombre de graphies à récupérer
-lexs
-lexiques source où le mots seront pris
-lists
-listes source où le mots seront pris
-externalFile
-fichier des mots à importer
-Response
-Status
-Response
-200
-La réponse sera une array de n graphies. Si n excède le nombre de mots de la cible, en récupérer le plus possible (0 le cas échéant). 
-400
-{"error":"invalid number"}
-400
-{"error":"Invalid lexique."}
-500
-{"error":"Something went wrong. Please try again later."}
- 3.4  importGraph
-Importe une liste de mots en provenance un fichier externe
-Permet d’importer des mots de fichiers externes en liste 4.7
-Use case : 4.7
-Lancé par : utilisateur
-Request
-Method
-URL            
-PUT
-api/extractGraph/
-Type
-Params
-Values
-PUT
-PUT
-externalFile
-user
-file
-user_id
-n (optionnal. Default : all)
-nombre de graphies à récupérer
-lexs
-lexiques source où le mots seront pris
-lists
-listes source où le mots seront pris
-externalFile
-fichier des mots à importer
-Response
-Status
-Response
-200
-Création d’une liste contenant les graphies présentes dans le fichier externe
-500
-{"error":"Something went wrong. Please try again later."}
- 4  Label
- 4.1  addLabel
-Ajoute un label sur un ensemble d’entrées ou de graphies
-    • lightShare d’une liste 4.2.2
-    • ajouter un label sur une entrée ou une sélection d’entrées 3.4.1
-    • ajoute un label sur une graphie
-Use case : 4.2.2, 3.4.1
-Lancé par : utilisateur, système
-Request
-Method
-URL            
-POST
-api/addLabel/
-Type
-Params
-Values
-POST
-POST
-POST
-POST
-POST
-POST
-Entrees
-lexs
-graphies
-nomLabel
-dueDate
-user
-array<Entrée lexicale>
-array<lexique>
-array<graphie>
-string
-date
-user_id
-entrees (optional)
-Sélection d’entrées dans un lexique
-lexs (optional)
-Lexiques correspondant aux entrees spécifiées précédemment
-graphies (optional)
-Sélection de graphies
-nomLabel
-Nom du label à ajouter
-dueDate (optional : pour les échances d’apprentissage)
-Date d’expiration du label
-Response
-Status
-Response
-200
-SI le label est déjà apposé à l’entrée, ne rien faire.
-SI nomLabel est un label existant : ajoute le label à l’entrée. 
-SI nomLabel n’existe pas encore : créer le label puis l’ajouter.
-401
-{"error":"Invalid entrees."}
-401
-{"error":"Invalid nomLabel."}
-500
-{"error":"Something went wrong. Please try again later."}
- 4.2  rmvLabel
-Enlève les labels sélectionnés à un ensemble de graphies ou d’entrées
-Use case : 3.4.6
-Lancé par : utilisateur, système
-Request
-Method
-URL            
-DELETE
-api/rmvLabel/
-Type
-Params
-Values
-DELETE
-DELETE
-DELETE
-DELETE
-entrees
-lexs
-graphs
-nomsLabels
-array<Entrée lexicale>
-array<lexique>
-array<graphie>
-array<string>
-entree (optional)
-Entrée lexicale
-lexs (optional)
-Lexiques correspondant aux entrées
-graphs (optional)
-Graphies dont on enlève le label
-nomsLabels
-Ensemble des labels à enlever
-Response
-Status
-Response
-200
-Retirer le label d’une entrée ou une graphie
-401
-{"error":"Invalid entrees."}
-401
-{"error":"Invalid nomsLabels."}
-500
-{"error":"Something went wrong. Please try again later."}
- 4.3  supprLabel
-Supprime complètement un label de la base et par cascade l’enlève donc de toutes les entrées auquel il est associé.
-Use case :
-Lancé par : utilisateur, système
-Request
-Method
-URL            
-DELETE
-api/supprLabel/
-Type
-Params
-Values
-DELETE
-nomLabel
-string
-nomLabel
-Nom du label à supprimer
-Response
-Status
-Response
-200
-Label supprimé
-401
-{"error":"Invalid nomLabel."}
-500
-{"error":"Something went wrong. Please try again later."}
- 4.4  setLabel
-Passe la partie numérique du label à un entier n
-Sert aussi pour le statut d’apprentissage : on considère que “connu” = 1 et “non connu” = 0
-Use case :
-Lancé par : système
-Request
-Method
-URL            
-POST
-api/setLabel/
-Type
-Params
-Values
-POST
-POST
-POST
-graphie
-nomLabel
-n
-string
-string
-integer
-Response
-Status
-Response
-200
-Exemple : 
-“A été trouvée dans MW 8 fois” -> “A été trouvée dans MW 43 fois”
-401
-{"error":"Invalid graphie."}
-401
-{"error":"Invalid nomLabel."}
-401
-{"error":"Invalid n."}
-500
-{"error":"Something went wrong. Please try again later."}
- 5  List
- 5.1  createList
-Crée une nouvelle liste
-Use case : 4.1
-Lancé par : utilisateur, système
-Request
-Method
-URL            
-POST
-api/createList/
-Type
-Params
-Values
-POST
-POST
-nomListe
-typeLise
-string
-string
-nomListe
-Nom de la liste
-typeListe
-personnelle, commune collaborative ou commune fixe
-Response
-Status
-Response
-200
-Un objet liste
-401
-{"error":"Invalid nomListe."}
-401
-{"error":"Invalid typeListe."}
-500
-{"error":"Something went wrong. Please try again later."}
- 5.2  supprList
-Supprime la liste sélectionnée
-Use case : 4.8
-Lancé par : utilisateur
-Request
-Method
-URL            
-DELETE
-api/supprList/
-Type
-Params
-Values
-DELETE
-liste
-liste
-Response
-Status
-Response
-200
-Liste supprimée
-401
-{"error":"Invalid nomListe."}
-401
-{"error":"Invalid typeListe."}
-500
-{"error":"Something went wrong. Please try again later."}
- 6  Lexicon
- 6.1  createLex
-Crée une nouveau lexique. Est lacée lorsqu’un nouveau groupe est crée par un utilisateur
-Use case : 6.1
-Lancé par : système
-Request
-Method
-URL            
-POST
-api/createLex/
-Type
-Params
-Values
-Response
-Status
-Response
-200
-Un objet lexique vide
-401
-{"error":"Invalid nomListe."}
-401
-{"error":"Invalid typeListe."}
-500
-{"error":"Something went wrong. Please try again later."}
- 6.2  supprLex
-Supprime le lexique sélectionné. Est lancé lorsqu’un utilisateur dissous un groupe.
-Use case : 6.6
-Lancé par : système
-Request
-Method
-URL            
-DELETE
-api/supprLex/
-Type
-Params
-Values
-DELETE
-lexique
-lexique
-Response
-Status
-Response
-200
-Lexique supprimée
-401
-{"error":"Invalid lexique."}
-500
-{"error":"Something went wrong. Please try again later."}
-Glossary
-Conventions
-    • Client - Client application.
-    • Status - HTTP status code of response.
-    • All the possible responses are listed under ‘Responses’ for each method. Only one of them is issued per request server.
-    • All response are in JSON format.
-    • All request parameters are mandatory unless explicitly marked as [optional]
-    • The type of values accepted for a request parameter are shown the the values column like this [10|<any number>] .The | symbol means OR. If the parameter is [optional], the default value is shown in blue bold text, as 10 is written in [10|<any number>].
-Status Codes
-All status codes are standard HTTP status codes. The below ones are used in this API.
-2XX - Success of some kind
-4XX - Error occurred in client’s part
-5XX - Error occurred in server’s part
-Status Code
-Description
-200
-OK
-201
-Created
-202
-Accepted (Request accepted, and queued for execution)
-400
-Bad request
-401
-Authentication failure
-403
-Forbidden
-404
-Resource not found
-405
-Method Not Allowed
-409
-Conflict
-412
-Precondition Failed
-413
-Request Entity Too Large
-500
-Internal Server Error
-501
-Not Implemented
-503
-Service Unavailable