# Introduction Grâce au projet participatif ORELC, **ORELC Connector API** fournit tous les mots contenus dans l'environnement ORELC. Un environnement qui croît sans cesse avec les ressources produites en shiKomori et les ajouts des contributeurs. **Quoi de mieux pour votre application ?** {% hint style="info" %} L'environnement ORELC * Le dictionnaire * Le dictionnaire des noms propres * Les ressources textuelles (ou articles) * Les proverbes et expressions {% endhint %} **ORELC Connector API,** c'est l'API généralement utilisée pour les échanges entre le serveur ORELC et les systèmes tiers utilisant des ressources en langue comorienne (shiMaore, shiMwali, shiNduani et shiNgazidja). Les applications comme [les claviers numériques](/cas-dutilisation/les-claviers-ou-editeurs-de-textes), [les logiciels de traitement de textes](/cas-dutilisation/les-claviers-ou-editeurs-de-textes), ou des systèmes de [traductions](/cas-dutilisation/les-traducteurs), utilisent l'API pour suggérer, enrichir, et/ou traduire des ressources en shiKomori vers le français et inversement. Pour voir les scenarios dans lesquels cette API pourrait être utilisée, consulter les [cas d'utilisation](/cas-dutilisation), ils pourront vous guider dans la mise en œuvre de votre solution. # Guide de développement Cette section décrit les 3 étapes pour développer son application : * **Tester dans l'environnement de démo** * **Développer votre application** * **Mettre en production** # Tester dans l'environnement de démo Pour une utilisation professionnelle ou libre, dans un environnement de démo ou en production, il vous faut une **API Key** (clé API). Elle est **la clé d'identification unique** de votre application avec le serveur ORELC. ## L'environnement de démo ### **Demander votre API Key** Demander une **clé API** (gratuite) pour votre application [ICI](https://developer.swadrii.com/), utile pour la mise en production. ### Utiliser les comptes tests Utiliser les comptes utilisateurs de démo ci-dessous pour tester l'authentification et récupérer les données. **Utilisateur test 1 :** * **username** : * **password** : Demo1234 **Utilisateur test 2 :** * **username** : * **password** : Demo1234 # Développer votre application ### Le numéro de version Ne faites pas de requêtes ou des traitements inutiles. Utiliser le numéro de **version** de l'objet **Dictionary** présent dans chaque requête, pour le comparer avec celui de votre application. Mettez à jour seulement si votre numéro de version est **inférieure à celui du serveur**. ### La synchronisation de votre application Privilégier les mises à jour **hebdomadaires ou mensuels.** En effet, bien qu'il est des ajouts de mots tous les jours sur ORELC, la validation de celles-ci **ne se font qu'au début du mois**. Il est donc inutile de vérifier le numéro de version de votre Dictionnaire ~~tous les X minutes ou x jours~~, faites-le de manière stratégique et intelligente afin de limiter les requêtes inutiles. ### L'authentification des utilisateurs ORELC Certains utilisateurs de votre application pourraient déjà avoir un compte ORELC (sur **[www.orelc.ac](http://www.orelc.ac)**), permettez-les de se connecter avec leurs identifiants dans votre application pour qui y retrouvent leurs avantages. ***Par exemple :** Votre application utilise **une API Key gratuite**. Elle ne reçoit donc q**u'un nombre limité de mots du dictionnaire**.* *A) L'utilisateur **John Doe** lui a un **compte ORELC**. En lui permettant de s'authentifier avec ses identifiants ORELC **dans votre application**, il pourra obtenir tous les mots du dictionnaire (+**6000** entrées en juillet 2021).* *B) L'utilisatrice **Janet Doe,** a une **licence de "Cours en ligne"** sur le site ORELC. En la permettant de s'authentifier avec ses identifiants ORELC **dans votre application**, elle pourra obtenir tous les mots de l'environnement ORELC (+**11 000** entrées en juillet 2021).* Consulter la section [Authentification ](/authentification)pour mettre en œuvre l'authentification des utilisateurs ORELC dans votre application. # Requêtes Les requêtes de l'API sont en **HTTPS** **POST\***, et les réponses au format **JSON**. Chaque requête est envoyée suivant ce format d'URL : ``` [Domaine]/academy/api/v1/Dictionary/getAccess/[Request] ``` * **Domaine** : Le nom du domaine de l'API * **Request** : Le nom de la requête a exécuter {% hint style="warning" %} N'oubliez pas de mettre le champ [**apiKey** ](/etape-de-developpement/1.-demander-une-api-key#1-1-utiliser-lapi-key-public)dans le header de vos requêtes. {% endhint %} # Réponses L'API répond aux requêtes **HTTPS POST** avec le contenu JSON. En cas de succès, le code d'état **est 200** et le contenu contient le résultat selon l'appel. Chaque réponse contient le champ **message**. Ce champ décrit **la cause de l'erreur** ou **une information de succès.** #### Exemple après une authentification réussie Code : `200 OK` ``` { "Dictionary": { "version": 1, "authorization": "all", "endValidity": "2022-07-16", "variety": "shiKomori", "entries": "10841/10841", "words": [ ... ] }, "message": "Votre licence expire le 2022-07-16. Vous disposez de 10841/10841 mots pour la suggestion automatique du clavier." } ``` #### Exemple, lorsqu'il y a une erreur d'authentification Code : `401 Unauthorized` ``` { "Dictionary": { "authorization": "none" }, "message": "AUTH - L'identifiant ou mot de passe est incorrect!" } ``` ### Les codes d'erreur * `400 Bad Request` - Cette erreur est renvoyée quand il y aune erreur de syntaxe dans la requête, ou qu'il manque un champ obligatoire. * `401 Unauthorized` - Cette erreur est causée pendant l'authentification cliente, quand il y a des identifiants ou une clé API invalides, ou quand le client n'a pas de permission pour accéder au Endpoint. * `403 Forbidden` - Cette erreur est renvoyée quand le client n'a pas les droits d'accès au contenu, donc le serveur refuse de donner la véritable réponse. * `405 Method Not Allowed` - Cette erreur est renvoyée quand la méthode n'est pas implémentée ou n'est pas autorisée par le serveur. * `408 Request Timeout` - Cette erreur est renvoyée quand il y a des requêtes lourdes qui prennent trop de temps à traiter (de l'ordre de dizaines de secondes). * `429 Too Many Requests` - Cette erreur est renvoyée quand l'utilisateur émet trop de requêtes dans un laps temps donné. * `500 Internal Server Error` - Cette erreur est renvoyée quand le serveur rencontre une situation qu'il ne sait pas traiter. # Mettre en production Toutes nos ressources/données sont fournies avec leurs annotations dialectales, nous vous demandons de préciser clairement, **le ou les dialectes utilisés** (shiMaore, shiMwali, shiNdzuani et/ou shiNgazidja) dans votre application. Ces informations de langue sont présentes dans le champ **variety** de l'objet **Dictionnary** ou de l'objet **Word**. ``` { "Dictionary": { "variety": "shiNdzuani", }, ..., } ``` ### Pour une application qui utilise une clé API gratuite Pour la promotion et le développement de la langue, si vous utilisez une clé API gratuite, **afficher le logo ORELC Open Data** comme indiqué ci-dessous. ![A la première page de mon application Open DATA](https://3275706340-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Md77_ChpDf2f-hH2vxw%2F-MeZ5ONIHHgGtBJdOnvz%2F-MeZ9L1ISXjEuMj155Md%2Fmon%20application.jpg?alt=media\&token=bfefc102-f00a-4175-ba50-98d307b292ba) {% hint style="info" %} Pour une application mobile, le logo ORELC Open Data doit apparaitre au lancement de l'application, **en bas et au centre de l'écran**. Pour un site web, le logo doit être visible dans le pied-de-page (footer) du site web. {% endhint %} ### Pour une application qui utilise une clé API Professionnelle Si vous utilisez une clé API Professionnelle, ou que votre application a été validé pour une certification, afficher le logo de votre certification comme indiqué ci dessous. ![](https://3275706340-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Md77_ChpDf2f-hH2vxw%2F-MenhD20E4jEK3Tmc9vE%2F-MenhLpQ1nm3MeXGK_35%2Fmon%20application_certifie.png?alt=media\&token=142bca4d-baf9-4ade-80c7-cd089aa25667) {% hint style="info" %} Pour une application mobile, [le logo](/images) de certification doit apparaitre au lancement de l'application, **en bas et au centre de l'écran**. Pour un site web, le logo doit être visible dans le pied-de-page (footer) du site web. * ORELC CERTIFIÉ SHIKOMORI pour une application qui traite 2 à 4 dialectes. * ORELC CERTIFIÉ SHIMAORE pour une application qui traite seulement le shiMaore. * ORELC CERTIFIÉ SHIMWALI pour une application qui traite seulement le shiMwali. * ORELC CERTIFIÉ SHINDZUANI pour une application qui traite seulement le shiNdzuani. * ORELC CERTIFIÉ SHINGAZIDJA pour une application qui traite seulement le shiNgazidja. {% endhint %} ### Les mentions Quelques soit votre clé API, mentionner le fournisseur ORELC dans la rubrique A PROPOS (ou équivalente) de votre application, avec une redirection vers le site web (facultative). Voir le champ **provider** et **web** de la requête [getAccess](/fonctionnalites/orelcaccess#requete). 
{ 
    ...    
    "provider": "ORELC",
    "web": "www.orelc.ac"   
}
[^1]: # Certifier votre application ### La certification Toutes les applications utilisant les données de l'API (**Open Data** ou **Data PRO**) peuvent être certifiées. Elles doivent dans ce cas afficher le logo de certification comme indiqué dans la section ["Mettre en production"](/etape-de-developpement/4.-mettre-en-production). Chaque application certifiée, est référencée sur le site ORELC puis recommandée dans nos réseaux sociaux. * **Site ORELC** : 7k utilisateurs uniques par mois (juin 2021) * **Membres ORELC** : 2,3k (juin 2021) * **Followers réseaux sociaux** : 4,5k cumulés (juin 2021) # Authentification ### Votre clé API Votre clé API est obligatoire pour l'authentification de votre compte développeur. Elle est à renseigner dans le Headers de chaque requête. **`Method`**`: POST` **`Domain`**`: www.orelc.ac` **`Type`****`:`**` ``API key.` **`Key`** **`:`**` ``Authorization` **`Value`**` ``: Votre clé API` #### Les paramètres du Headers **(aperçu avec Postman)** ![Aperçu Postman](https://3275706340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Md77_ChpDf2f-hH2vxw%2Fuploads%2Fd96NAtHUhCZvGJgjxYCk%2FAuthorization.png?alt=media\&token=141a15da-bda3-46ea-8260-00e174aead87) ### L'authentification utilisateur L'authentification utilisateur permet aux utilisateurs de retrouver les avantages liés à leur compte/abonnement ORELC. **`Method`**`: POST` **`Domain`**`: https://orelc.ac` **`Username`**` ``: L'identifiant du compte ORELC.` **`Password`**` ``: Le mot de passe du compte ORELC.` #### Les paramètres d'authentification utilisateur (aperçu avec Postman) : ![](https://3275706340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Md77_ChpDf2f-hH2vxw%2Fuploads%2FOMRcM59iDQg35N8JbRrr%2FHeaders.png?alt=media\&token=3ce34f7e-fbfe-4b6e-9066-a59947c4fbad) {% hint style="success" %} Même s'il est recommandé de mettre en place une authentification ORELC dans son application, l'authentification utilisateur n'est pas obligatoire pour récupérer les données. Si l'utilisateur n'a pas de compte ORELC ou ne souhaite pas se connecter pour récupérer ses droits, ce sont les droits de votre clé API (**Open Data** ou **Data PRO**) qui seront utilisés pour la récupération des données. {% endhint %} # Requêtes Dans cette section est décrite les requêtes disponibles de l''API. ## Utilisateur * **checkUser :** Vérifie si les identifiants de l'utilisateur ORELC sont valides * **getAccess :** Retourne les droits d'accès d'un utilisateur * **createUser** : Crée un utilisateur dans l'environnement ORELC ## Dictionnaire * **getList** : Retourne les mots du dictionnaire sous forme de liste * **getLexicon** : Retourne les mots du dictionnaire sous forme d'objets * **getProperNouns** : Retourne les noms propres du dictionnaire sous formes d'objet * **getWordsOfDay** : Retourne les mots du jour * **getRecentWords** : Retourne les mots ajoutés récemment * **getRecentDefinitions** : Retourne les mots définis récemment * **translate** : Traduit une entrée # checkUser ## Requête Permet de vérifier les identifiants utilisateurs. #### Endpoint ``` [Domain]/academy/api/v1/Dictionary/checkUser ``` #### Exemple {% tabs %} {% tab title="Javascript" %} 
const endpoint = "[endpoint]";
const apiKey = "[myAPIKey]";
const username = "[username]"; 
const password = "[password]";

fetch(endpoint, {
    method: "POST", 
    headers: {
        "Authorization": apiKey,
        "username ": username,
        "password ": password 
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Erreur :", error));
{% endtab %} {% tab title="PHP" %} ```php $endpoint = "[endpoint]"; $apiKey = "[myAPIKey]"; $username = "[username]"; $password = "[password]"; // Prepare data for POST request $data = [ "username" => $username, "password" => $password ]; # Prepare request headers $options = [ "http" => [ "header" => "Authorization: $apiKey\r\n" . "Content-type: application/x-www-form-urlencoded\r\n", "method" => "POST", "content" => http_build_query($data) ] ]; // Send POST request and get response $context = stream_context_create($options); $response = file_get_contents($endpoint, false, $context); if ($response === FALSE) { echo "Erreur : Impossible de récupérer la réponse."; } else { echo $response; } ``` {% endtab %} {% tab title="Python " %} ```python import requests endpoint = "[endpoint]" api_key = "[myAPIKey]" username = "[username]" password = "[password]" # Prepare data for POST request data = { "username": username, "password": password } # Prepare request headers headers = { "Authorization": api_key } # Send POST request and get response response = requests.post(endpoint, headers=headers, data=data) if response.status_code == 200: print(response.json()) else: print("Erreur :", response.text) ``` {% endtab %} {% endtabs %} ### Réponse ```json { "success": true, "message": "Identifiants valides" } ``` ### Description des champs | success | boolean | true si les identifiants sont correctes, autrement false | false | | ------- | ------- | -------------------------------------------------------- | ----- | | message | string | Message d'informations/erreurs | | # getAccess ## Requête Permet de récupérer les droits de l'Utilisateur pour le [Dictionnaire](/objets/dictionary), sa [Licence ](/objets/license)ainsi que les mentions. La réponse retourne un array d'objets [License](/objets/license), et un [User](/objets/user). #### Endpoint ``` [Domain]/academy/api/v1/Dictionary/getAccess ``` #### Exemple {% tabs %} {% tab title="Javascript" %} 
const endpoint = "[endpoint]";
const apiKey = "[myAPIKey]";

// Use the username and password to obtain data based on user rights
const username = "[username]"; // optionnel
const password = "[password]"; // optionnel

fetch(endpoint, {
    method: "POST", 
    headers: {
        "Authorization": apiKey,
        "username ": username,
        "password ": password 
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Erreur :", error));
{% endtab %} {% tab title="Second Tab" %} {% endtab %} {% endtabs %} ### Réponse ```json { "Dictionary": { "variety": "shiKomori", "authorization": "all", "startValidity": "2021-01-06", "endValidity": "2022-01-06", "entries": "11554/11554", "licenseNumber": 40, "userNumber": 36, "version": 1 }, "Licenses": [ { "number": 40, "name": "Apprendre à Parler", "description": "" } ], "User": { "number": 36, "firstName": "John", "lastName": "DOE", "displayName": "John Doe" }, "message": "Utilisation des données Apprendre à Parler.", "provider": "ORELC", "web": "www.orelc.ac" } ``` ### Description des champs | champ | Type | Description | Valeur par défaut | | -------- | ------ | ------------------------------ | ------------------------------- | | message | string | Message d'informations/erreurs | | | provider | URL | Nom du fournisseur | ORELC | | web | URL | Lien du fournisseur | | #### Dictionary | Champ | Type | Description | Valeur par défaut | | ------------- | ------- | ------------------------------------- | ------------------------------------------------------------- | | variety | string | Filtrage du contenu | shiKomori \| shiMaore \| shiMwali \| shiNdzuani \| shiNgzidja | | authorization | string | Droit utilisateur sur le dictionnaire | all \| demo \| none | | startValidity | string | Date de début de validité | yyyy-mm-dd (peut être vide) | | endValidity | string | Date de fin de validité | yyyy-mm-dd (peut être vide) | | entries | string | Nombre d'entrées autorisées | 1000 | | licenseNumber | integer | Numéro de licence | ∞ | | userNumber | integer | Numéro de l'utilisateur | ∞ | | version | integer | Numéro de version du dictionnaire | 1 | #### Licenses | Champ | Type | Description | Valeur par défaut | | ----------- | ------- | ----------------- | ----------------- | | number | integer | Numéro de licence | ∞ | | name | integer | Nom | ∞ | | description | string | Description | | #### User | Champ | Type | Description | Valeur par défaut | | ----------- | ------- | ----------------------- | ----------------- | | number | integer | Numéro de l'utilisateur | ∞ | | firstName | string | Prénom | non nul | | lastName | string | Nom | non nul | | displayName | string | Nom d'affichage | | # getList ## Requête Permet de récupérer la liste de tous les entrées en shiKomori. La réponse est retournée dans un array de string. #### Endpoint ``` [Domain]/academy/api/v1/Dictionary/getList ``` #### Exemple {% tabs %} {% tab title="Javascript" %} ```javascript const endpoint = "[endpoint]"; const apiKey = "[myAPIKey]"; // Use the username and password to obtain data based on user rights const username = "[username]"; // optionnel const password = "[password]"; // optionnel fetch(endpoint, { method: "POST", headers: { "Authorization": apiKey, "username ": username, "password ": password } }) .then(response => response.json()) .then(data => console.log(data)) .catch(error => console.error("Erreur :", error)); ``` {% endtab %} {% tab title="Second Tab" %} {% endtab %} {% endtabs %} ## Réponse ```javascript { "Dictionary": { "version": 1, "authorization": "all", "endValidity": "2022-01-06", "variety": "shiKomori", "entries": "11554/11554", "list": [ "aɓiria", "aɓuyati", "adhan", "adjaɓu", "adjali", "âdui", "âɗa", "na", "mila", "aɗaɓu", "nfu", "afa", "âfia", "Afrika", "Ya", "Kusini", "âfu", "alahulia", "alakini", "alama", "alifu", "alifuɓe", "alikoli", "Araɓu", "mia", "arɓaini", ... ] } } ``` {% hint style="warning" %} Avec une **authorization** de démo, cette requête ne renvoie qu'un nombre limité de mots. Le nombre de mots du dictionnaire est inscrits dans le champ **entries.** Vous pouvez vous servir des champs **authorization** et **entries** pour en informer l'utilisateur. {% endhint %} ### Description des champs | Champ | Type | Description | Valeur | | ---------- | ---------- | ------------------ | ------ | | Dictionary | Dictionary | Objet dictionnaire | | | list | array | Liste de mots | | | | | | | # getLexicon ## Requête Permet de récupérer les mots. La réponse retourne un array d'objets [word](/objets/word). #### Endpoint ``` [Domain]/academy/api/v1/Dictionary/getLexicon ``` #### Body ```json { "letter" : "a", "fromLanguage" : "km", "toLanguage" : "fr" } ``` {% tabs %} {% tab title="Javascript" %} ```javascript const endpoint = "[endpoint]"; const apiKey = "[myAPIKey]"; // Use the username and password to obtain data based on user rights const username = "[username]"; // optionnel const password = "[password]"; // optionnel fetch(endpoint, { method: "POST", headers: { "Authorization": apiKey, "Content-Type": "application/json", "username ": username, "password ": password }, body: JSON.stringify({ letter: "a", fromLanguage: "km", toLanguage: "fr" }) }) .then(response => response.json()) .then(data => console.log(data)) .catch(error => console.error("Erreur :", error)); ``` {% endtab %} {% tab title="Second Tab" %} {% endtab %} {% endtabs %} Description des champs de la requête | Champ | Type | Description | Valeur | | ------------ | ------- | --------------------------------------------------------------------------- | ----------- | | letter | string | La lettre initiale des mots du lexique | requise | | fromLanguage | string | La langue d'entrée (ISO 639-1) | requise | | toLanguage | string | La langue de traduction (ISO 639-1) | requise | | varieties | boolean | false, pour masquer les informations des dialectes (valeur par defaut true) | optionnelle | | | | | | ## Réponse 
{
    "Dictionary": {
        "version": 7,
        "authorization": "all",
        "endValidity": "",
        "variety": "shiKomori ●",
        "entries": "213/213",
        "words": [
            {
                "id": 1065,
                "hasDefinition": false,
                "km": "-a",
                "fr": [
                    "à",
                    "de"
                ],
                "isShimaore": true,
                "isShimwali": true,
                "isShindzuani": true,
                "isShingazidja": true,
                "dialectSymbols": "●"
            },
            {
                "id": 1066,
                "hasDefinition": true,
                "km": "-a âiɓu",
                "fr": [
                    "immoral (d'-)",
                    "obscène (d'-)"
                ],
                "isShimaore": false,
                "isShimwali": false,
                "isShindzuani": true,
                "isShingazidja": true,
                "dialectSymbols": "▲  ◼"
            },
            {
                "id": 1101,
                "hasDefinition": false,
                "km": "aɓaɗan",
                "fr": [
                    "jamais"
                ],
                "isShimaore": true,
                "isShimwali": true,
                "isShindzuani": true,
                "isShingazidja": true,
                "dialectSymbols": "●"
            },
            {
                "id": 1103,
                "hasDefinition": true,
                "km": "aɓuɗu (u-)",
                "fr": [
                    "vénérer"
                ],
                "isShimaore": true,
                "isShimwali": true,
                "isShindzuani": true,
                "isShingazidja": true,
                "dialectSymbols": "●"
            }
        ]
    },
    ...
}
{% hint style="warning" %} Avec une **authorization** de démo, cette requête ne renvoie qu'un nombre limité de mots. Le nombre de mots du dictionnaire est inscrits dans le champ **entries.** Vous pouvez vous servir des champs **authorization** et **entries** pour en informer l'utilisateur. {% endhint %} Description des champs de la réponse | Champ | Type | Description | | ----- | ----- | -------------------------------------------------------------- | | words | array | La liste d'objet [word ](/objets/word)au format entrée/valeurs | | | | | # getProperNouns ## Requête Permet de récupérer les noms propres dans le format de l'objet [name](/objets/name). #### Endpoint ``` [Domain]/academy/api/v1/Dictionary/getProperNouns ``` #### Body ```json { "letter" : "a", "fromLanguage" : "km", "toLanguage" : "fr" } ``` {% tabs %} {% tab title="Javascript" %} ```javascript const endpoint = "[endpoint]"; const apiKey = "[myAPIKey]"; // Use the username and password to obtain data based on user rights const username = "[username]"; // optionnel const password = "[password]"; // optionnel fetch(endpoint, { method: "POST", headers: { "Authorization": apiKey, "Content-Type": "application/json", "username ": username, "password ": password }, body: JSON.stringify({ letter: "a", fromLanguage: "km", toLanguage: "fr" }) }) .then(response => response.json()) .then(data => console.log(data)) .catch(error => console.error("Erreur :", error)); ``` {% endtab %} {% tab title="Second Tab" %} {% endtab %} {% endtabs %} Description des champs de la requête | Champ | Type | Description | Valeur | | ------------ | ------ | -------------------------------------- | ------- | | letter | string | La lettre initiale des mots du lexique | requise | | fromLanguage | string | La langue d'entrée (ISO 639-1) | requise | | toLanguage | string | La langue de traduction (ISO 639-1) | requise | ## Réponse ```json { "Dictionary": { "version": 7, "authorization": "demo", "endValidity": "", "variety": "shiKomori ●", "entries": "14/42", "names": [ { "id": 277, "hasDefinition": true, "km": "Abdu-Swamad", "fr": "Abdou-Soimad" }, { "id": 328, "hasDefinition": true, "km": "Âfu", "fr": "Anfu" }, { "id": 86, "hasDefinition": false, "km": "Aida", "fr": "Aïda" }, { "id": 225, "hasDefinition": false, "km": "Aisate", "fr": "Aïssate" }, { "id": 226, "hasDefinition": false, "km": "Aisati", "fr": "Aïssati" }, { "id": 160, "hasDefinition": true, "km": "Alawi", "fr": "Allaoui" } ] }, ... } ``` {% hint style="warning" %} Avec une **authorization** de démo, cette requête ne renvoie qu'un nombre limité de mots. Le nombre de mots du dictionnaire est inscrits dans le champ **entries.** Vous pouvez vous servir des champs **authorization** et **entries** pour en informer l'utilisateur. {% endhint %} Description des champs de la réponse | Champ | Type | Description | | ----- | ----- | --------------------- | | names | array | La liste d'objet name | | | | | # getWordsOfDay ## Requête Permet de récupérer les mots du jour. La réponse retourne un array d'objets [word](/objets/word). #### Endpoint ``` [Domain]/academy/api/v1/Dictionary/getWordsOfDay ``` #### Body ```json { "size" : 3, "toLanguage" : "fr" } ``` {% tabs %} {% tab title="Javascript" %} ```javascript const endpoint = "[endpoint]"; const apiKey = "[myAPIKey]"; // Use the username and password to obtain data based on user rights const username = "[username]"; // optionnel const password = "[password]"; // optionnel fetch(endpoint, { method: "POST", headers: { "Authorization": apiKey, "Content-Type": "application/json", "username ": username, "password ": password }, body: JSON.stringify({ "size" : 3, "toLanguage" : "fr" }) }) .then(response => response.json()) .then(data => console.log(data)) .catch(error => console.error("Erreur :", error)); ``` {% endtab %} {% tab title="Second Tab" %} {% endtab %} {% endtabs %} Description des champs de la requête | Champ | Type | Description | Valeur | | ---------- | ------- | ----------------------------------- | ------------------------- | | size | integer | nombre de mots à retourner | optionnelle (default : 3) | | toLanguage | string | La langue de traduction (ISO 639-1) | optionnelle (default fr) | ## Réponse ```json { "Dictionary": { "version": 1, "authorization": "demo", "endValidity": "", "variety": "shiKomori ●", "entries": "3/3", "words": [ { "id": 1514, "hasDefinition": true, "km": "gari", "fr": [ "véhicule", "voiture" ] }, { "id": 7386, "hasDefinition": false, "km": "gunguni", "fr": [ "refrigerateur", "frigo" ] }, { "id": 6395, "hasDefinition": true, "km": "firigo", "fr": [ "frigo", "réfrigérateur" ] } ] }, ... } ``` Description des champs de la réponse | Champ | Type | Description | | ----- | ----- | ---------------------------------------------- | | words | array | La liste d'objet word au format entrée/valeurs | | | | | # getRecentWords ## Requête Permet de récupérer les mots récents. La réponse retourne un array d'objets [word](/objets/word). #### Endpoint ``` [Domain]/academy/api/v1/Dictionary/getRecentWords ``` #### Body ```json { "size" : 3, "toLanguage" : "fr" } ``` {% tabs %} {% tab title="Javascript" %} ```javascript const endpoint = "[endpoint]"; const apiKey = "[myAPIKey]"; // Use the username and password to obtain data based on user rights const username = "[username]"; // optionnel const password = "[password]"; // optionnel fetch(endpoint, { method: "POST", headers: { "Authorization": apiKey, "Content-Type": "application/json", "username ": username, "password ": password }, body: JSON.stringify({ "size" : 3, "toLanguage" : "fr" }) }) .then(response => response.json()) .then(data => console.log(data)) .catch(error => console.error("Erreur :", error)); ``` {% endtab %} {% tab title="Second Tab" %} {% endtab %} {% endtabs %} Description des champs de la requête | Champ | Type | Description | Valeur | | ---------- | ------- | ----------------------------------- | ------------------------- | | size | integer | nombre de mots à retourner | optionnelle (default : 3) | | toLanguage | string | La langue de traduction (ISO 639-1) | optionnelle (default fr) | ## Réponse ```json { "Dictionary": { "version": 1, "authorization": "demo", "endValidity": "", "variety": "shiKomori ●", "entries": "3/3", "words": [ { "id": 8013, "hasDefinition": false, "km": "mongozi", "fr": [ "guide", "meneur" ] }, { "id": 8011, "hasDefinition": false, "km": "upotro", "fr": [ "gaucherie", "maladresse" ] }, { "id": 8010, "hasDefinition": false, "km": "Mngu", "fr": [ "Dieu" ] } ] }, ... } ``` Description des champs de la réponse | Champ | Type | Description | | ----- | ----- | ---------------------------------------------- | | words | array | La liste d'objet word au format entrée/valeurs | | | | | # getRecentDefinitions ## Requête Permet de récupérer les définitions récentes. La réponse retourne un array d'objets [word](/objets/word). #### Endpoint ``` [Domain]/academy/api/v1/Dictionary/getRecentDefinitions ``` #### Body ```json { "size" : 3, "toLanguage" : "fr" } ``` {% tabs %} {% tab title="Javascript" %} ```javascript const endpoint = "[endpoint]"; const apiKey = "[myAPIKey]"; // Use the username and password to obtain data based on user rights const username = "[username]"; // optionnel const password = "[password]"; // optionnel fetch(endpoint, { method: "POST", headers: { "Authorization": apiKey, "Content-Type": "application/json", "username ": username, "password ": password }, body: JSON.stringify({ "size" : 3, "toLanguage" : "fr" }) }) .then(response => response.json()) .then(data => console.log(data)) .catch(error => console.error("Erreur :", error)); ``` {% endtab %} {% tab title="Second Tab" %} {% endtab %} {% endtabs %} Description des champs de la requête | Champ | Type | Description | Valeur | | ---------- | ------- | ----------------------------------- | ------------------------- | | size | integer | nombre de mots à retourner | optionnelle (default : 3) | | toLanguage | string | La langue de traduction (ISO 639-1) | optionnelle (default fr) | ## Réponse 
{
    "Dictionary": {
        "version": 1,
        "authorization": "demo",
        "endValidity": "",
        "variety": "shiKomori ●",
        "entries": "3/3",
        "words": [
            {
                "id": 1771,
                "hasDefinition": true,
                "km": "kaɓla",
                "fr": [
                    "avant"
                ]
            },
            {
                "id": 4256,
                "hasDefinition": true,
                "km": "kafe",
                "fr": [
                    "café"
                ]
            },
            {
                "id": 5441,
                "hasDefinition": true,
                "km": "kaka (u-)",
                "fr": [
                    "faire caca",
                    "déféquer"
                ]
            }
        ]
    },
    ...
}
Description des champs de la réponse | Champ | Type | Description | | ----- | ----- | ---------------------------------------------- | | words | array | La liste d'objet word au format entrée/valeurs | | | | | # translate ## Requête Permet de traduire une entrée. La réponse retourne un array d'objets [word](/objets/word). #### Endpoint ``` [Domain]/academy/api/v1/Dictionary/translate ``` #### Body ```json { "entry" : "uleza", "languages" : "fr" } ``` #### Exemple {% tabs %} {% tab title="Javascript" %} ```javascript const endpoint = "[endpoint]"; const apiKey = "[myAPIKey]"; // Use the username and password to obtain data based on user rights const username = "[username]"; // optionnel const password = "[password]"; // optionnel fetch(endpoint, { method: "POST", headers: { "Authorization": apiKey, "Content-Type": "application/json", "username ": username, "password ": password }, body: JSON.stringify({ "entry" : "uleza", "languages" : "fr" }) }) .then(response => response.json()) .then(data => console.log(data)) .catch(error => console.error("Erreur :", error)); ``` {% endtab %} {% tab title="Second Tab" %} {% endtab %} {% endtabs %} Description des champs de la requête | Champ | Type | Description | Valeur | | --------- | ------ | ------------------------------------------- | ------- | | entry | string | L'entrée à traduire | requise | | languages | string | La langue de traduction au format ISO 639-2 | requise | | | | | | ## Réponse ```json { "Dictionary": { "version": 7, "authorization": "all", "endValidity": "", "variety": "shiKomori", "entries": "1/1", "word": { "leza (u-)": [ "rendre ivre", "anesthésier" ], "isShimaore": false, "isShimwali": false, "isShindzuani": false, "isShingazidja": true, "dialectSymbols": "◼" } } ... } ``` {% hint style="warning" %} Avec une **authorization** de démo, cette requête ne renvoie qu'un nombre limité de mots. Le nombre de mots du dictionnaire est inscrits dans le champ **entries.** Vous pouvez vous servir des champs **authorization** et **entries** pour en informer l'utilisateur. {% endhint %} Description des champs de la réponse | Champ | Type | Description | | ----- | ------ | ----------- | | word | object | Objet word | | | | | # createUser ## Requête Permet de créer un utilisateur. #### Endpoint ```url [Domain]/academy/api/v1/Dictionary/createUser ``` #### Body ```json { "sex" : "M", "email" : "johndoe@email.com", "firstName" : "John", "lastName" : "Doe", "password" : "123456", "dialect" : "wni" "shikomoriLevel" : 1 } ``` #### Exemple {% tabs %} {% tab title="Javascript" %} ```javascript const endpoint = "[endpoint]"; const apiKey = "[myAPIKey]"; fetch(endpoint, { method: "POST", headers: { "Authorization": apiKey, "Content-Type": "application/json", }, body: JSON.stringify({ "sex" : "M", "email" : "johndoe@email.com", "firstName" : "John", "lastName" : "Doe", "password" : "123456", "dialect" : "wni" "shikomoriLevel" : 1 }) }) .then(response => response.json()) .then(data => console.log(data)) .catch(error => console.error("Erreur :", error)); ``` {% endtab %} {% tab title="Second Tab" %} {% endtab %} {% endtabs %} Description des champs de la requête | Champ | Type | Description | Valeur | | -------------- | ------- | ---------------------------------------------------- | ------- | | sex | string | L'entrée à traduire | requise | | email | string | Email de connexion | requise | | firstName | string | Prénom | requise | | lastName | string | Nom de famille | requise | | password | string | Mot de passe | requise | | dialect | string | [Variété linguistique ](/langues/dialect)(ISO 639-3) | requise | | shikomoriLevel | integer | Niveau de langue | requise | ## Réponse ```json { "success": true, "message": "Félicitations ! Votre compte a été crée avec succès. Vous pouvez maintenant vous connecter." } ``` Description des champs de la réponse | Champ | Type | Description | | ------- | ------- | --------------------------------------------------------- | | success | boolean | Renvoie true si l'utilisateur a été crée, autrement false | | message | string | Information sur l'exécution de la requête | # Requêtes dépréciées Dans cette section est listée les requêtes dépréciées et leur date limite de fonctionnement. # getAll ## Requête (dépréciée) Cette requête est fonctionnelle jusqu'au 31/12/23, utiliser plutôt la requête [getList](/fonctionnalites/getall) pour récupérer la liste des mots. Permet de récupérer la liste de tous les entrées en shiKomori de l'environnement ORELC. ``` [Domain]/academy/api/v1/Dictionary/getAll ``` ## Réponse ``` { "Dictionary": { "version": 1, "authorization": "all", "endValidity": "2022-01-06", "variety": "shiKomori", "entries": "11554/11554", "words": [ "aɓiria", "aɓuyati", "adhan", "adjaɓu", "adjali", "âdui", "âɗa", "na", "mila", "aɗaɓu", "nfu", "afa", "âfia", "Afrika", "Ya", "Kusini", "âfu", "alahulia", "alakini", "alama", "alifu", "alifuɓe", "alikoli", "Araɓu", "mia", "arɓaini", ... ] } } ``` {% hint style="warning" %} Avec une **authorization** de démo, cette requête ne renvoie qu'un nombre limité de mots. Le nombre de mots du dictionnaire est inscrits dans le champ **entries.** Vous pouvez vous servir des champs **authorization** et **entries** pour en informer l'utilisateur. {% endhint %} ### Description des champs | Champ | Type | Description | Valeur | | ---------- | ---------- | ------------------ | ------ | | Dictionary | Dictionary | Objet dictionnaire | | | words | array | Liste de mots | | | | | | | # Objets Dans cette section est décrite la liste des objets utiles * [Dictionary](/objets/dictionary) - Le dictionnaire * [Word ](/objets/word)- Le mot # License L'objet License contient les informations détaillés de la licence de l'utilisateur. | Champ | description | | ----------- | ------------------------------------------------------------- | | number | Le numéro de la licence (peut être utilisé comme identifiant) | | name | Le nom | | description | La description | # User L'objet User contient les informations détaillés de l'utilisateur. | Champ | description | | ---------------- | --------------------------------------------------------------- | | number | Le numéro de l'utilisateur, peut être utilisé comme identifiant | | sex | Le genre (Féminin, Masculin, Autre) | | firstName | Le prénom | | lastName | Le nom de famille | | displayName | Le nom d'affichage | | language | La variété linguistique | | learningLanguage | La langue d'apprentissage | # Dictionary L'objet Dictionnaire contient les informations courantes du dictionnaire ORELC. Il permet de connaitre les informations utiles et les différentes autorisations pour la mise à jour de celui-ci. | Champ | Description | | ------------- | ----------------------------------------------------------- | | version | Le n° de version du dictionnaire, utile pour la mise à jour | | authorization | Les droits utilisateurs | | startValidity | La date de début de validité des droits utilisateurs | | endValidity | La date de fin de validité des droits utilisateurs | | entries | Le nombre de résultats obtenu par rapport au nombre réel. | # word L'objet word contient les informations détaillés du mot. | Champ | description | | -------------- | ---------------------------------------------------------- | | km | Le(s) mot(s) en shiKomori | | fr | Le(s) mot(s) en français | | hasDefinition | true, si le mot à une définition, autrement false | | isShimaore | true, si le mot employé est du shiMaore autrement false | | isShimwali | true, si le mot employé est du shiMwali autrement false | | isShindzuani | true, si le mot employé est du shiNdzuani autrement false | | isShingazidja | true, si le mot employé est du shiNgazidja autrement false | | dialectSymbols | indique les symboles des dialectes utilisés | # name L'objet name contient les informations détaillés du nom propre. | Champ | description | | ------------- | ------------------------------------------------- | | gender | Le [genre ](#le-genre)du nom propre | | km | Le nom transcrit en shiKomori | | fr | Le nom transcrit en français | | hasDefinition | true, si le nom à une définition, autrement false | #### Le genre Le champ **gender** peut avoir les valeurs suivantes : * M (male), pour les noms masculins * F (female), pour les noms féminins * FM (female-male), pour les noms féminins et masculins * G (geography), pour les noms de géographie # Langues Dans cette section est listée les langues et les variétés linguistiques prises en charge. ## Liste des langues et dialectes prises en charge #### Les langues | Langue | Code ISO-639-2 | Symbol | Code couleur HEXA | | --------- | -------------------------------------------------- | ------ | ----------------- | | français | FR | aucun | aucun | | anglais | EN | aucun | aucun | | shiKomori | non codifié, utiliser le code pays KM (ISO 3166-1) | ● | #008000 | #### Les dialectes | Dialecte | Code ISO-639-3 | Symbol | Code couleur HEXA | | ----------- | -------------- | ------ | ----------------- | | shiMaore | swb | ✧ | #808080 | | shiMwali | wlc | ✽ | #FDCC41 | | shiNdzuani | wni | ▲ | #FF0000 | | shiNgazidja | zdj | ◼ | #1AA3FF | {% hint style="info" %} Les symboles des dialectes comoriens sont utilisés en tant qu'annotation dans l'environnement ORELC et les ouvrages du professeurs Mohamed Ahmed-Chamanga, afin de repérer rapidement les mots appartenant à une variété précise du shiKomori. Vous pouvez les utiliser dans votre système si vous traiter plusieurs dialectes du shiKomori. {% endhint %} # dialect Le champ dialecte correspond à la variété linguistique de l'utilisateur. Il peut avoir les valeurs suivants : | valeur | description | | ------ | -------------------------- | | swb | code langue du shiMaore | | wlc | code langue du shiMwali | | wni | code langue du shiNdzuani | | zdj | code langue du shiNgazidja | # shikomoriLevel Le champ shikomoriLevel correspond au niveau de langue de l'utilisateur. Il peut avoir les valeurs suivants : | valeur | description | | ------ | -------------------- | | 1 | Niveau Débutant | | 2 | Niveau Intermédiaire | | 3 | Niveau Confirmé | | 4 | Niveau Avancé | # Cas d'utilisation Cette section décrit comment utiliser ORELC Connector API afin de mettre en œuvre des scénarios bien connus. Même si vous intégrez un type de système différent, il constitue un bon point de départ pour les modèles et pratiques d'utilisation de l'API. Ici les différents cas d'utilisation dans lesquels l'API peut être utilisée * **Clavier numérique** * **Editeur ou Traitement de textes** * **Traducteur / IA** * **Jeux de mots** ## # Les claviers ou éditeurs de textes Avec ORELC les mots, les phrases et leurs bonnes orthographes sont la base pour assurer le bon développement de la langue. Tous les systèmes de traitement de texte récupèrent et mettent à jour leur base de données avec la garantie de toujours avoir les nouveaux mots et dans la bonne orthographe. ## L'auto-complétions ou la suggestion de mots L'auto-complétions est la fonction incontournable de tous les logiciels de traitement de textes et des claviers numériques. Récupérer tous les mots, les verbes à l'infinitif et les verbes conjugués dans une simple liste en JSON pour un traitement rapide. Actuellement (juin 2021) plus de 10 000 entrées sont enregistrées et chaque jours des centaines de mots sont vérifiés et ajoutés ! ## La correction orthographique Les éditeurs de textes peuvent maintenant prendre en charge la langue comorienne. Actuellement (juin 2021) plus de 10 000 entrées sont enregistrées et chaque jours des centaines de mots sont vérifiés et ajoutés ! # Les traducteurs # Images Dans cette section toutes les images utiles à télécharger pour votre application. ### Le pack de logo ORELC Open Data ![Logo ORELC Open Data](https://3275706340-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Md77_ChpDf2f-hH2vxw%2F-MeZ5-w-KgknPtVCDb_Z%2F-MeZ5F6OdDeGUqXRuTK3%2Forelc_open_data_v2.png?alt=media\&token=6395a6df-72ff-4422-8967-6932f051f547) ### Le pack de logo de certification ![Logo ORELC Certifié shiKomori](https://3275706340-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Md77_ChpDf2f-hH2vxw%2F-MeouIG-AgEARu3DBhuC%2F-MeoyaOsRIaCJpQa_8gv%2Forelc_shikomori_certifie_flou.png?alt=media\&token=2806acdb-8828-44e4-aa58-5954ad37e87d) {% hint style="warning" %} Ci-dessus est une illustration flouté du logo, le pack de logos certifiés est envoyé seulement sous condition d'une certification. {% endhint %}