应用程序接口

API Options Navigation-zh — API选项页面显示了用户凭证

Habitica的应用程序接口（API）允许程序员创建与Habitica交互的第三方应用程序，扩展和其他工具。使用“API选项”分页的用户凭证，软件可获得对用户的Habitica有限的访问权限，让软件能显示并能够更改用户的数据和界面。

第四版API（请勿使用）[]

Habitica的工作人员正在创建Habitica的第四版API，但仍在开发、未完成且任何理由及任何第三方工具都不适用。它随时可能在没通知的情况更改且更改后所有使用它的工具都会无法使用。即使没有更改，任何使用它的工具的访问也会被无预警阻止而没有警告。第三版API是第三方工具应使用的唯一版本。

在Habitica V3 API Documentation你可以看到部分第四版的入口。请忽视它们。

第三版API[]

Habitica API的第3版发布于2016年5月21日。所有第三方软件都应使用此版本。API的版本1和2已关闭且无法使用。

以下资源可帮助你更新已编写或创建的新工具：

Habitica V3 API Documentation
Guidance for Comrades页面有创建第三方软件前应阅读的有用且重要的信息
在Aspiring Comrades公会提问并寻求帮助

API文档中的错误[]

如果你在API文档中发现错误（包括拼写错误或误导性文字）请在Report a Bug公会回报错误。如果你不确定它是否是个错误，你可以在Aspiring Comrades公会询问。

使用API[]

请将HTTPS请求发送到Habitica的服务器以使用API。请求的URL定义了要获取的信息类型或要进行的更新类型。支持的URL列在API's documentation。

许多网址包含变量以获取特定的数据或更新（例如指定一个要修改的特定任务）。

变量名以冒号为前缀，如:variableName。使用時应该替换所有内容，包含整个字串和冒号。例如，Group - Get group的路由是https://habitica.com/api/v3/groups/:groupId，因此对于ID为12345678-90ab-40a4-cdef-1234567890ab的group就会是https://habitica.com/api/v3/groups/12345678-90ab-40a4-cdef-1234567890ab
有些路由有多个变量，則必须全部替换，例如User - Hatch a pet是https://habitica.com/api/v3/user/hatch/:egg/:hatchingPotion
当想查询变量所拥有的内容类型时，你可以从Content - Get all available content objects（https://habitica.com/api/v3/content）路由找到适当的值。例如，:egg可以是TigerCub，:hatchingPotion可以是CottonCandyBlue。

大多数API路由需要用户ID和API令牌进行认证，你必須使用header keys x-api-user和x-api-key（分别用于用户ID和API令牌）添加到请求的HTTP headers中，別用任何其他方式指定它们（请参见下面的示例）。

如果你要在脚本或其他工具中使用API路由，或者在命令行上多次使用它，你必须得使用x-client header key。正如同志指南中的“X-Client标头”章节所述，该键的值应该要是你的用户ID和工具名称。如果你还没创建一个完整的工具，只是想试试API的使用方式，可以使用“Test”之类的称呼来代替你的工具名称。最重要的是，阅读同志指南以了解有关正确使用X-Client的信息。

如何将x-api-user、x-api-key和x-client headers添加到API调用取决于你发出请求的方式。

对于shell脚本，你可以选择使用curl命令行工具来发送HTTPS请求。若选择这个方法，你必须使用如下所示的URL格式和身份验证headers：

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" \
    -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing"

你也可以选择使用httpie发送请求

http GET https://habitica.com/api/v3/user Content-Type:application/json x-api-user:12345678-90ab-416b-cdef-1234567890ab x-api-key:12345678-90ab-416b-cdef-1234567890ab x-client:12345678-90ab-416b-cdef-1234567890ab
-Testing

至於使用JavaScript的jQuery Ajax request，你可以用以下类似的代码：

    $.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');
                xhr.setRequestHeader('x-client', '12345678-90ab-416b-cdef-1234567890ab-MyHabiticaApp');
            },
        success: yourFunctionToProcessTheData,
        error: yourFunctionToReportAnError,
    });

如果你允许其他用户使用你的脚本或工具，你需要将x-api-user和x-api-key的值放入到API调用中，这些变量包含使用工具的用户的用户ID和API令牌。值得注意的是，x-client header不应包含该用户的ID - 它应该始终是你自己的用户ID，因为你是该工具的作者。有关这方面的更多信息，包含使用变量的示例代码，请参阅同志指南中的“X-Client标头”章节。

每个API路由使用一种HTTP请求方法，例如GET、POST、PUT或DELETE，在文档中用彩色标签表示。在你的代码中使用正确的方法很重要（例如，见上面的type: 'GET'的例子）。不同的请求方式使用不同的机制以指定变量和他们的值：

对GET请求，请在查询字符串中指定它们。例如，https://habitica.com/api/v3/groups?type=party,guilds

对POST、PUT和DELETE请求，请在body中指定参数信息。执行此操作的方法取决于你如何发出请求。对于HTML表单，请使用form fields，例如input和textarea。jQuery提供了一个jQuery.post()方法。对于curl，请使用-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" \
    -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing" \
    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" \
    -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing" \
    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" \
    -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing" \
    https://habitica.com/api/v3/user

当需要在array或对象中指定数据时，请使用带有{ ... }和[ ... ]的构造函数，例如在这个例子中，创建了一个有两个标签的待办事项和一个包含两个项目的列表：

curl -X POST \
    -d '{
        "type": "todo",
        "text": "task title",
        "tags": [
            "12345678-90ab-416b-cdef-1234567890ab",
            "abcdef12-90ab-416b-cdef-1234567890ab"
        ],
        "checklist": [
            { "text": "1st checklist item", "completed": false },
            { "text": "2nd checklist item", "completed": false }
        ],
        "collapseChecklist": true
        }' \
    -H "Content-Type: application/json" \
    -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" \
    -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" \
    -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing" \
    https://habitica.com/api/v3/tasks/user

来自API的回应及错误信息[]

每个对API发出的请求都会获得一个带有HTTP状态码和body的响应。

如果请求成功，会得到2xx状态码并且body的success属性将被设置为true。

如果请求失败，会得到4xx或5xx状态码，body的success属性将被设置为false，错误的具体信息将在body的error和message属性中出现。这是关于失败的唯一信息来源，但它应该包含你找出问题原因所需的一切。

如果你需要关于错误的建议，请在Aspiring Comrades公会中询问。询问时记得附上失败的整个API命令（删除你的API令牌！）和完整的错误信息（若有必要，删去任何私人信息）。

提示[]

要找到你的宝石数量，使用/api/v3/user GET route並找到data.balance的值。将其乘以4得到宝石的数量。balance是等价于宝石数量的美元，$1为4个宝石。

扩展和插件页面有许多可以让API的使用变得更简单的工具。它们被列在“现有的应用与扩展”表格中，其中“类型”栏位为"API"的项目。

第二版API[]

此区块的信息是关于第二版API，目前已关闭并无法使用。这个信息仅作为协助你升级现存工具至版本三的参考而留存。

扩展和脚本可以在个别任务上使用Habitica的加分/扣分系统。一个利用这一点的扩展的例子是Chrome Extension，它会在你访问高效网站时进行加分，并在你访问拖延相关的网站时进行减分。其他扩展和脚本的例子包括各种番茄钟工具、Anki扩展和GitHabit，它们会因良好行为而给你加分，并因不良行为而降低你的分数。

对于扩展和脚本，Habitica有一个用于对第三方习惯进行加分和减分的简单API。程序员应该发出一个HTTP POST请求到：

/api/v2/user/tasks/{id}/{direction}

{id}是由小写字母组成的任务的唯一标识符。尽量试着让它简单明了，如“productivity”或“fitness”，因为其他服务可能会在你的任务之上运作。举例来说，当你访问坏习惯相关的网站（reddit、9gag等）时，Chrome扩展会降低“生产力”任务的分数。然而，当你完成一项任务时，番茄钟会提高“生产力”的分数。所以两个服务共用一个任务来为你的整体生产力评分。如果该任务还不存在，则会在你第一次POST到该URL时创建它。
{direction}为“up”或“down”
需要一个包含API令牌的POST body

举例来说，这个applescript命令加上一个计时器可以定期給一个习惯加分。用你的用户ID和API Key替换xxxxx。更改“productivity”为任何你想命名的习惯。

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"

第一版API[]

第一版API已被关闭且不可用。