JIRA-REST APIs 簡介

簡介

Jira的REST APIs 被用於jira服務器應用之間的遠程交互，jira軟件和service desk應用的REST APIs擁有其應用特定的特徵，例如sprint或者消費者請求。

授權與認證

授權與認證可以採用以下兩種方式之一：

• OAuth 1.0a
• Basic Authentication

URL結構

REST API可以讓我們通過URL路徑來訪問jira應用的資源，使用REST API，應用需要創建HTTP的請求並對響應進行解析。

JIRA REST API使用JSON作爲它的通信格式並且採用了例如GET、PUT、POST、和DELETE等HTTP方法。JIRA的URLs通常爲以下的結構：

http://host:port/context/rest/api-name/api-version/resource-name

使用REST APIs

下面的主題是關於如何使用Jira REST APIs，以及如何使用它們進行交互。

Expansion

爲了簡化API的響應，Jira REST API使用資源擴展。這意味着API將會返回明確請求的資源的那部分。這會幫助你避免在請求的資源過多或過少時發生的問題。

你可以使用expand查詢參數來指定一個你想要展開的實體的逗號分隔的列表，並根據名稱來標識它們。

下面的例子展開了issue JRA-9的name和renderedFields：

https://jira.atlassian.com/rest/api/latest/issue/JRA-9?expand=names,renderedFields

返回的信息如下：

{
    "expand": "widgets",
    "self": "http://jira.atlassian.com/rest/api/resource/KEY-1",
    "widgets": { "widgets": [], "size": 5 }
}

Pagination

Jira使用分頁來限制返回資源的尺寸。一個分頁API的請求將會返回如下的結構：

{
    "startAt" : 0,
    "maxResults" : 10,
    "total": 200,
    "values": [
        { /* result 0 */ },
        { /* result 1 */ },
        { /* result 2 */ }
    ]
}

• startAt：返回列表中該頁起始的元素
• maxResults：每頁返回的項目的個數
• total：返回項目的總數
• isLastPage：當前頁是否爲最後一頁

客戶端可以使用startAt、maxResults和total來從返回結果中獲取想要得到的數據。

Ordering

有些資源支持對特定的域進行排序，這個功能由一個orderBy查詢參數提供。

排序支持升序和降序。可用“+”和“-”來分別指定升序和降序。默認的，排序是升序的。例如，?orderBy=+name。

Self links

許多域有一個自鏈接來讓你訪問該資源的規範位置。例如：

"reporter": {
    "self": "http://jira.atlassian.com/rest/api/2/user?username=admin",
    "name": "admin",
    "emailAddress": "[email protected]",
    "displayName": "Administrator",
    "active": true
},

創建一個GET請求給自鏈接有時候能夠提供給你過關於這個域的額外的信息。

特殊請求和響應的報頭

• X-AUSERNAME 包含授權用戶或者匿名者的用戶名的響應報頭
• X-Atlassian-Token 接受複數部分或表單數據的方法將只會執行擁有X-Atlassian-Token：no-check報頭的請求

錯誤響應

多數資源會然會一個帶狀態碼的響應報文，通常，返回的實體的json如下所示：

{
    "id": "https://docs.atlassian.com/jira/REST/schema/error-collection#",
    "title": "Error Collection",
    "type": "object",
    "properties": {
        "errorMessages": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "errors": {
            "type": "object",
            "patternProperties": {
                ".+": {
                    "type": "string"
                }
            },
            "additionalProperties": false
        },
        "status": {
            "type": "integer"
        }
    },
    "additionalProperties": false
}

域輸入格式

Summary

一個單行文本的系統域

"summary": "This is an example summary"

Description

一個多行文本的系統域

"description": "This is an example description with multiples lines of text\n separated by\n line feeds"

Components

一個有多個鍵值對構成的系統域：

"components" : [ { "name": "Active Directory"} , { "name": "Network Switch" } ]

Due date

一個以“YYYY-MM-DD”格式保存日期的系統域：

"duedate" : "2015-11-18"

Labels

一個有字符串列表構成的系統域：

"labels" : ["examplelabelnumber1", "examplelabelnumber2"]

Checkbox custom Field

一個自定義的域，允許你從一個已定義的數值列表中選擇複數值。你能夠根據value或ID來找到它們。

"customfield_11440" : [{ "value" : "option1"}, {"value" : "option2"}]
"customfield_11440" : [{ "id" : 10112}, {"id" : 10115}]

Date picker custom field

一個“YYYY-MM-DD”格式的日期的自定義域：

"customfield_11441" : "2015-11-18"

Data time picker custom field:

一個“ ISO 8601 YYYY-MM-DDThh:mm:ss.sTZD ”格式的時間的自定義域：

"customfield_11442" : "2015-11-18T14:39:00.000+1100"

Labels custom field

一個字符串列表構成的自定義域：

"customfield_11443" : [ "rest_label1", "rest_label2" ]

Number custom field

一個包含一個數字的自定義域：

"customfield_11444" : 123

…其它域說明詳見官網