功能日记

REST API v1.3.0:Agile部分能力开放


在此次版本更新中,REST API开放了Agile的部分能力,这意味着企业内部系统可以通过REST API对Worktile Agile的部分资源进行操作,例如:查看、创建和更新工作项(工作项包括:史诗、特性、用户故事、任务、缺陷和事务)等等。

使用者是谁?

本次开放的REST API,支持两类使用者:企业身份和个人身份。

企业身份需要通过Client Credentials的方式获取身份令牌,使用者可以查看和操作所有已开放的资源,例如:获取企业内所有的工作项。

个人身份需要通过Authorization Code的方式获取身份令牌,使用者只能查看和操作自己有权限的已开放的资源,例如:获取企业成员自己能看到的工作项等等。

查看项目

您可以使用REST API获取项目信息。目前对外开放的项目属性包括:项目名、项目类型、项目标识、项目主题色、项目描述和项目成员。

查看示例数据

查看迭代

您可以使用REST API获取迭代信息,目前对外开放的迭代属性包括:所属项目、迭代负责人、迭代名称、开始时间、结束时间、迭代状态和迭代目标。

查看示例数据

查看看板、看板栏和泳道

您可以使用REST API获取看板、看板栏和泳道信息,目前看板对外开放的属性包括:所属项目、看板名和看板支持的工作项类型,目前看板栏对外开放的属性包括:看板栏名、在制品限制数和完成的定义,目前泳道对外开放的属性包括泳道名称等。

查看示例数据

查看版本

您可以使用REST API获取到版本信息。目前对外开放的版本属性包括:所属项目、版本负责人、版本名、开始时间、结束时间和版本状态。

查看示例数据

创建、更新和查看工作项

您可以使用REST API创建、更新和查看工作项。工作项共有6种类型:史诗、特性、用户故事、任务、缺陷和事务。每一种工作项开放的数据不相同,因此在创建和更新工作项时所使用的的REST API接口也不相同,例如创建史诗时使用的接口为`POST /agile/epics`,而创建用户故事时使用的接口为`POST /agile/stories`,因此具体使用时需要参考文档。在获取工作项时,所有的工作项都共用同一个获取接口`GET /agile/work_items/{work_item_id}`,但是根据工作项类型的区别,工作项的数据结构有所不同,在使用接口返回值时需要通过`type`属性进行区分。

下面是一个用户故事的结构示例:

{
    "id": "5edca112b06305c524cad2fa",
    "url": "https://open.worktile.com/v1/agile/work_items/5edca112b06305c524cad2fa",
    "project": {
       	...
    },
    "version": {
        ...
    },
    "sprint": {
        ...
    },
    "board": null,
    "entry": null,
    "swimlane": null,
    "state": {
        ...
    },
    "priority": {
        ...
    },
    "identifier": "SCR-3",
    "type": "story",
    "title": "这是一个用户故事",
    "description": "这是一个用户故事的描述",
    "parent": {
        ...
    },
    "assignee": {
        ...
    },
    "start_at": 1583290309,
    "end_at": 1583290347,
    "participants": [
        ...
    ],
    "story_points": 1
}

详细文档地址

其他相关的基础数据

在此次更新中,还提供一些基础数据的获取接口。例如:企业成员、工作项状态、工作项优先级。

具体请参考Worktile REST API文档