動作

Redmine API¶

Redmine 透過 REST API 公開部分資料。此 API 提供對以下所述資源的存取權限和基本 CRUD 操作（建立、更新、刪除）。 API 支援 XML 和 JSON 格式。

API 說明¶

資源	狀態	備註	可用性
議題	穩定		1.0
專案	穩定		1.0
專案成員	Alpha		1.4
使用者	穩定		1.1
工時記錄	穩定		1.1
新聞	原型	僅適用於 `index` 的原型實作	1.1
議題關聯	Alpha		1.3
版本	Alpha		1.3
Wiki 頁面	Alpha		2.2
查詢	Alpha		1.3
附件	Beta	1.4 版中新增透過 API 新增附件的功能	1.3
議題狀態	Alpha	提供所有狀態的清單	1.3
追蹤器	Alpha	提供所有追蹤器的清單	1.3
列舉	Alpha	提供議題優先順序和時間追蹤活動的清單	2.2
議題分類	Alpha		1.3
角色	Alpha		1.4
群組	Alpha		2.1
自訂欄位	Alpha		2.4
搜尋	Alpha		3.3
檔案	Alpha		3.4
我的帳戶	Alpha		4.1
日誌	Alpha		5.0

狀態圖例

穩定 - 功能完整，沒有計畫進行重大變更
Beta - 可用於整合，但可能存在一些錯誤或缺少次要功能
Alpha - 主要功能已到位，需要 API 使用者和整合者的回饋
原型 - 非常粗略的實作，版本中期可能會發生重大變更。**不建議用於整合**
已計畫 - 計畫在未來版本中提供，具體取決於開發人員的可用性

您可以查看每個版本的 API 變更清單。

一般主題¶

在 `POST`/`PUT` 請求上指定 `Content-Type`¶

建立或更新遠端元素時，即使遠端 URL 已相做標記，也**必須**指定請求的 Content-Type（例如 POST ../issues.json）

對於 JSON 內容，必須將其設定為 Content-Type: application/json。
對於 XML 內容，必須將其設定為 Content-Type: application/xml。

驗證¶

大多數情況下，API 需要驗證。要啟用 API 樣式驗證，您必須在「管理」->「設定」->「API」中勾選「啟用 REST API」。然後，可以使用以下兩種不同方式進行驗證：

通過 HTTP 基本驗證使用您的常規登錄名/密碼。
使用您的 API 金鑰，這是一種避免在腳本中放入密碼的簡便方法。API 金鑰可以通過以下方式之一附加到每個請求：
- 作為「key」參數傳遞
- 通過 HTTP 基本驗證作為用戶名和隨機密碼傳遞
- 作為「X-Redmine-API-Key」HTTP 標頭傳遞（在 Redmine 1.1.0 中添加）

登錄後，您可以在帳戶頁面（/my/account）的默認佈局右側窗格中找到您的 API 金鑰。

用戶模擬¶

從 Redmine 2.2.0 開始，您可以通過在 API 請求中設定「X-Redmine-Switch-User」標頭來模擬用戶。它必須設定為用戶登錄名（例如，'X-Redmine-Switch-User: jsmith'）。這僅在使用管理員帳戶使用 API 時有效，在使用普通用戶帳戶使用 API 時，將忽略此標頭。

如果使用「X-Redmine-Switch-User」標頭指定的登錄名不存在或未激活，您將收到 412 錯誤響應。

集合資源和分頁¶

對集合資源（例如「/issues.xml」、「/users.xml」）的 GET 請求的響應通常不會返回資料庫中可用的所有物件。Redmine 1.1.0 引入了一種使用以下參數查詢此類資源的通用方法：

「offset」：要檢索的第一個物件的偏移量
「limit」：響應中存在的項目數（默認為 25，最大值為 100）

範例

GET /issues.xml
=> returns the 25 first issues

GET /issues.xml?limit=100
=> returns the 100 first issues

GET /issues.xml?offset=30&limit=10
=> returns 10 issues from the 30th

對集合資源的 GET 請求的響應提供了有關 Redmine 中可用的物件總數以及響應使用的偏移量/限制的信息。範例：

GET /issues.xml

<issues type="array" total_count="2595" limit="25" offset="0">
  ...
</issues>

GET /issues.json

{ "issues":[...], "total_count":2595, "limit":25, "offset":0 }

注意：如果您使用的 REST 客戶端不支持此類頂級屬性（total_count、limit、offset），則可以將「nometa」參數或「X-Redmine-Nometa」HTTP 標頭設定為 1 以獲取沒有它們的響應。範例：

GET /issues.xml?nometa=1

<issues type="array">
  ...
</issues>

獲取關聯數據¶

從 1.1.0 開始，您必須通過將「include」參數附加到查詢 URL 來明確指定要包含在查詢結果中的關聯：

範例

要檢索帶有其描述的問題日誌：

GET /issues/296.xml?include=journals

<issue>
  <id>296</id>
  ...
  <journals type="array">
  ...
  </journals>
</issue>

您也可以使用逗號分隔的項目列表加載多個關聯。

範例

GET /issues/296.xml?include=journals,changesets

<issue>
  <id>296</id>
  ...
  <journals type="array">
  ...
  </journals>
  <changesets type="array">
  ...
  </changesets>
</issue>

使用自定義欄位¶

大多數 Redmine 物件都支持自定義欄位。它們的值可以在「custom_fields」屬性中找到。

XML 範例

GET /issues/296.xml      # an issue with 2 custom fields

<issue>
  <id>296</id>
  ...
  <custom_fields type="array">
    <custom_field name="Affected version" id="1">
      <value>1.0.1</value>
    </custom_field>
    <custom_field name="Resolution" id="2">
      <value>Fixed</value>
    </custom_field>
  </custom_fields>
</issue>

JSON 範例

GET /issues/296.json      # an issue with 2 custom fields

{"issue":
  {
    "id":8471,
    ...
    "custom_fields":
      [
        {"value":"1.0.1","name":"Affected version","id":1},
        {"value":"Fixed","name":"Resolution","id":2}
      ]
  }
}

您還可以使用相同的語法在創建/更新物件時設定/更改自定義欄位的值（除非不需要自定義欄位名稱）。

XML 範例

PUT /issues/296.xml

<issue>
  <subject>Updating custom fields of an issue</subject>
  ...
  <custom_fields type="array">
    <custom_field id="1">
      <value>1.0.2</value>
    </custom_field>
    <custom_field id="2">
      <value>Invalid</value>
    </custom_field>
  </custom_fields>
</issue>

注意：「custom_fields」XML 標籤上的「type="array"」屬性是嚴格要求的。

JSON 範例

PUT /issues/296.json

{"issue":
  {
    "subject":"Updating custom fields of an issue",
    ...
    "custom_fields":
      [
        {"value":"1.0.2","id":1},
        {"value":"Invalid","id":2}
      ]
  }
}

附加檔案¶

Redmine 1.4.0 中添加了對通過 REST API 添加附件的支持。

首先，您需要使用 POST 請求將每個檔案上傳到「/uploads.xml」（或「/uploads.json」）。請求正文應為您要附加的檔案的內容，並且「Content-Type」標頭必須設定為「application/octet-stream」（否則您將收到「406 Not Acceptable」響應）。如果上傳成功，您將獲得一個 201 響應，其中包含已上傳檔案的權杖。

然後，您可以使用此權杖將您上傳的檔案附加到新問題或現有問題。

XML 範例

首先，上傳您的檔案：

POST /uploads.xml?filename=image.png
Content-Type: application/octet-stream
...
(request body is the file content)

# 201 response
<upload>
  <token>7167.ed1ccdb093229ca1bd0b043618d88743</token>
</upload>

然後使用上傳權杖創建問題：

POST /issues.xml
<issue>
  <project_id>1</project_id>
  <subject>Creating an issue with a uploaded file</subject>
  <uploads type="array">
    <upload>
      <token>7167.ed1ccdb093229ca1bd0b043618d88743</token>
      <filename>image.png</filename>
      <description>An optional description here</description>
      <content_type>image/png</content_type>
    </upload>
  </uploads>
</issue>

如果您嘗試上傳超過允許最大大小的檔案，您將收到 422 回應

POST /uploads.xml?filename=image.png
Content-Type: application/octet-stream
...
(request body larger than the maximum size allowed)

# 422 response
<errors>
  <error>This file cannot be uploaded because it exceeds the maximum allowed file size (1024000)</error>
</errors>

JSON 範例

首先，上傳您的檔案：

POST /uploads.json?filename=image.png
Content-Type: application/octet-stream
...
(request body is the file content)

# 201 response
{"upload":{"token":"7167.ed1ccdb093229ca1bd0b043618d88743"}}

然後使用上傳權杖創建問題：

POST /issues.json
{
  "issue": {
    "project_id": "1",
    "subject": "Creating an issue with a uploaded file",
    "uploads": [
      {"token": "7167.ed1ccdb093229ca1bd0b043618d88743", "filename": "image.png", "content_type": "image/png"}
    ]
  }
}

您也可以上傳多個檔案（透過對 /uploads.json 進行多個 POST 請求），然後建立一個包含多個附件的問題

POST /issues.json
{
  "issue": {
    "project_id": "1",
    "subject": "Creating an issue with a uploaded file",
    "uploads": [
      {"token": "7167.ed1ccdb093229ca1bd0b043618d88743", "filename": "image1.png", "content_type": "image/png"},
      {"token": "7168.d595398bbb104ed3bba0eed666785cc6", "filename": "image2.png", "content_type": "image/png"}
    ]
  }
}

驗證錯誤¶

當您嘗試使用無效或遺漏的屬性參數建立或更新物件時，您將收到 422 Unprocessable Entity 回應。這表示無法建立或更新物件。在這種情況下，回應主體包含相應的錯誤訊息

XML 範例:

# Request with invalid or missing attributes
POST /users.xml
<user>
  <login>john</login>
  <lastname>Smith</lastname>
  <mail>john</mail>
</uer>

# 422 response with the error messages in its body
<errors type="array">
  <error>First name can't be blank</error>
  <error>Email is invalid</error>
</errors>

JSON 範例:

# Request with invalid or missing attributes
POST /users.json
{
  "user":{
    "login":"john",
    "lastname":"Smith",
    "mail":"john" 
  }
}

# 422 response with the error messages in its body
{
  "errors":[
    "First name can't be blank",
    "Email is invalid" 
  ]
}

JSONP 支援¶

Redmine 2.1.0+ API 支援 JSONP 從不同網域的 Redmine 伺服器請求資料（例如，使用 JQuery）。可以使用 callback 或 jsonp 參數傳遞回呼。從 Redmine 2.3.0 開始，JSONP 支援是可選的，預設情況下處於禁用狀態，您可以在管理 -> 設定 -> API 中勾選「啟用 JSONP 支援」來啟用它。

範例

GET /issues.json?callback=myHandler

myHandler({"issues":[ ... ]})

各種語言/工具中的 API 使用¶

API 變更歷史記錄¶

本節列出可能破壞回溯相容性的現有 API 功能的變更。API 的新功能列在 API 說明中。

2012-01-29：多選自訂欄位 (r8721, 1.4.0)¶

Redmine 現在支援具有多個值的客製化欄位，並且可以在 API 回應中找到。這些客製化欄位具有 multiple=true 屬性，並且其 value 屬性是一個陣列。

範例

GET /issues/296.json

{"issue":
  {
    "id":8471,
    ...
    "custom_fields":
      [
        {"value":["1.0.1","1.0.2"],"multiple":true,"name":"Affected version","id":1},
        {"value":"Fixed","name":"Resolution","id":2}
      ]
  }
}

檔案 (0)

由 Go MAEDA 更新於超過 2 年前 · 102 個修訂已鎖定

專案

一般

個人檔案

Redmine

最新版本¶

資源¶

Wiki

Redmine API¶

API 說明¶

一般主題¶

在 `POST`/`PUT` 請求上指定 `Content-Type`¶

驗證¶

用戶模擬¶

集合資源和分頁¶

獲取關聯數據¶

使用自定義欄位¶

附加檔案¶

驗證錯誤¶

JSONP 支援¶

各種語言/工具中的 API 使用¶

API 變更歷史記錄¶

2012-01-29：多選自訂欄位 (r8721, 1.4.0)¶

專案

一般

個人檔案

Redmine

最新版本¶

資源¶

Wiki

Redmine API¶

API 說明¶

一般主題¶

在 POST/PUT 請求上指定 Content-Type¶

驗證¶

用戶模擬¶

集合資源和分頁¶

獲取關聯數據¶

使用自定義欄位¶

附加檔案¶

驗證錯誤¶

JSONP 支援¶

各種語言/工具中的 API 使用¶

API 變更歷史記錄¶

2012-01-29：多選自訂欄位 (r8721, 1.4.0)¶

在 `POST`/`PUT` 請求上指定 `Content-Type`¶