Application Programming Interface

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'API[]

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:

Habitica V3 API Documentation
The Forge - Le blog officiel d'Habitica pour les Forgerons (en anglais):
- API v2 Deprecation Notice
- API v2 -> v3 Migration Guide
- Overview of Changes in Version 3 of the API - les principales différences entre les versions 2 et 3
La guilde Aspiring Blacksmiths (Coders of Habitica) pour poser des questions et demander de l'aide
Habitica's GitHub repository pour du support technique et signaler des problèmes avec l'API (par exemple des erreurs ou de la documentation déroutante)

Erreurs dans la documentation API[]

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'API[]

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).

Les noms de variable commencent par deux points comme dans :nomdeVariable. Le String entier, avec les deux points et le nom, doit être remplacé. Par exemple, la route Group - Get group https://habitica.com/api/v3/groups/:groupId et donc, pour l'ID de groupe 12345678-90ab-40a4-cdef-1234567890ab, vous utiliseriez https://habitica.com/api/v3/groups/12345678-90ab-40a4-cdef-1234567890ab
Certaines routes ont plus d'une variable et toutes doivent être remplacées, par exemple User - Hatch a pet est https://habitica.com/api/v3/user/hatch/:egg/:hatchingPotion
Lorsque les variables se référent à des types de contenu, vous pouvez trouver les valeurs appropriées de la route Content - Get all available content objects (https://habitica.com/api/v3/content). Par exemple, :egg peut être TigerCub et :hatchingPotion peut être CottonCandyBlue

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'API[]

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'API[]

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