FANDOM


MESSAGE IMPORTANT SI VOUS CONTRIBUEZ AU DÉVELOPPEMENT DU SITE :

  • La version 3 de l'API d'Habitica a été publiée le 21 mai.
  • La version 2 a été désactivée le 30 juillet. Tous les outils tiers qui utilisent encore la version 2 ne fonctionnent plus depuis cette date.
  • Apprenez en plus sur la page Application Programming Interface et dans la section "Changements d'API" du Guide de la forge.

API Options Navigation

L'onglet des Options API montre les identifiants d'utilisateur

L'Application Programming Interface (API) d'Habitica permet aux programmeurs de créer des applications, extensions et d'autres outils tiers qui s'intègrent avec Habitica. Avec les identifiants d'utilisateur affichées dans l'onglet des Options API, le software peut obtenir un accès limité au compte Habitica d'un•e utilisateur•trice, lui permettant d'afficher et potentiellement de modifier les données et les préférences de l'utilisateur•trice.

Version 3 de l'APIModifier

Le 21 mai 2016, la version 3 de l'API d'Habitica a été publiée. Tous les nouveaux logiciels tiers devraient l'utiliser et tous les logiciels existants devraient l'utiliser. Les versions 1 et 2 ont été désactivées et ne peuvent pas être utilisées.

Les ressources suivantes existent pour vous aider à mettre à jour les outils que vous avez codé ou pour en créer de nouveaux:

Erreurs dans la documentation APIModifier

Si vous trouvez des erreurs dans la documentation API, signalez les dans la guilde "Report a Bug" ou déposez une Pull request. Elles seront probablement corrigées rapidement mais cela peut prendre quelques jours avant que les corrections soient déployées sur le site web.

Il n'y a en ce moment à notre connaissance pas d'erreurs dans la documentation de l'API.

Utiliser l'APIModifier

Pour utiliser l'API, vous envoyez des demandes HTTPS au serveur d'Habitica. L'URL de la demande définit le type d'information que vous voulez obtenir ou le type de mise à jour que vous souhaitez faire. Les URL prisent en charge sont listées dans la documentation API.

Beaucoup d'URL contiennent des variables pour inclure plus de détails sur le type de données à obtenir ou modifier (par exemple pour préciser une tâche particulière à modifier).

La plupart des routes d'API demandent un ID d'utilisateur et jeton d'API pour l'authentification, ceux-ci doivent être précisés dans les entêtes HTTP de la demande (n'essayez pas de les préciser d'une autre manière) en utilisant respectivement les clés d'entête x-api-user et x-api-key pour votre ID d'utilisateur et jeton d'API. La façon dont vous les ajouter aux entêtes dépend de la manière dont vous placez les demandes.

  • Pour les scripts shell, vous pouvez choisir d'utiliser l'outil de ligne de commande curl pour envoyer les requêtes HTTP. Dans ce cas, formatez l'URL et l'authentification des en-têtes comme ceci:
    curl https://habitica.com/api/v3/user -s -X GET --compressed -H "Content-Type:application/json" -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab"
  • Pour JavaScript en utilisant une requête jQuery Ajax, vous pouvez utiliser un code similaire à celui-ci:
        $.ajax({
            url: 'https://habitica.com/api/v3/user',
            type: 'GET',
            dataType: 'json',
            cache: false,
            beforeSend: function(xhr){
                    xhr.setRequestHeader('x-api-user', '12345678-90ab-416b-cdef-1234567890ab');
                    xhr.setRequestHeader('x-api-key',  '12345678-90ab-416b-cdef-1234567890ab');
                },
            success: yourFunctionToProcessTheData,
            error: yourFunctionToReportAnError,
        });
    

Chaque route API utilise l'une des méthodes de requête HTTP, comme GET, POST, PUT ou DELETE, indiquée par les labels de couleur dans la documentation. Il est important d'utiliser la méthode correcte correspondante dans votre code (voir les exemples type: 'GET' ci-dessus). Les différentes méthodes de requêtes utilisent des mécanismes différentes pour spécifier les variables et leur valeurs:

  • Pour les requêtes GET, spécifiez les dans le string query. Par exemple, https://habitica.com/api/v3/groups?type=party,guilds
  • Pour les requêtes POST, PUT et DELETE, spécifiez-les dans les paramètres de corps. La méthode pour faire cela dépends de comment vous placez vos requêtes. Pour les formulaires HTML, utilisez les champs du formulaire comme input et textarea. jQuery fournit une méthode jQuery.post(). Pour curl, utilisez l'option -d :
    curl -X POST -d "type=todo&text=New Task Text&notes=Some Notes" -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" https://habitica.com/api/v3/tasks/user
    curl -X PUT -d "text=Edited Task Text" -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" https://habitica.com/api/v3/tasks/7d4a623d-0a2c-48e2-b9d9-feea1fa2d467
    curl -X DELETE -d "password=yourPasswordGoesHere" -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" https://habitica.com/api/v3/user
    

Version 2 de l'APIModifier

IMPORTANT: Les informations contenues dans cette section se rapportent à la version 2 de l'API, qui a été désactivée et n'est plus utilisée. Ces informations demeurent uniquement comme référence pour vous aider à mettre à jour les outils existants avec la version 3 de l'API.

Les extensions et scripts pouvaient utiliser le sytème de marquage des points haut/bas pour les tâches individuelles. Un exemple d'extension qui utilisait cela est l'Extension Chrome, qui marquait vers le haut pour les sites web productifs visités et vers le bas pour avoir visité des sites webs servant à la procrastination. D'autres exemples d'extensions et de scripts qui marquaient  des habitudes positivement pour un bon comportement et négativement pour un mauvais comportement sont les outils liés aux Pomodoros , l'Anki Extension et GitHabit.

Pour les extensions et scripts, Habitica avait un API simple pour marquer positivement ou négativement des habitudes tierces. Les programmeurs devaient envoyer un HTTP POST à:

/api/v2/user/tasks/{id}/{direction}
  • {id} est un identifiant unique pour une tâche consistent en une série de lettres en minuscule. Essayez d'en faire quelque chose de simple et clair comme 'productivite' ou 'fitness', parce que d'autres services peuvent utiliser la même tâche. Par exemple, l'extension Chrome marque une tâche de 'productivite' vers le bas lorsque vous visitez un site qui vous fait procrastiner (reddit, 9gag, etc). Cependant, Pomodoro marque 'productivite' vers le haut lorsque vous complétez une tâche. Ainsi les deux services partagent une seule tâche pour marquer votre productivité générale. Si la tâche n'existe pas encore, elle est créée la première fois que vous envoyez un POST à cette URL.
  • {direction} est 'up' ou 'down'
  • Un corps POST consistant en jeton d'API est requis

Par exemple, cette commande applescript liée à un timer peut marquer une habitude + à intervales réguliers. Remplacez xxxxx par votre ID d'utilisateur et clé d'API. Modifiez 'productivity' pour le nom que vous voulez donner à votre habitude.

do shell script "curl -X POST --compressed -H 'Content-Type:application/json' -H 'x-api-user: xxxxx' -H 'x-api-key: xxxxx' https://habitica.com/api/v2/user/tasks/productivity/up"

Version 1 de l'APIModifier

La version 1 de l'API est désactivée et n'est plus utilisée.

Sauf mention contraire, le contenu de la communauté est disponible sous licence CC-BY-SA .