動作

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`¶

建立或更新遠端元素時，必須指定請求的 Content-Type，即使遠端 URL 已相應地加上後綴（例如 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 標頭來模擬用戶使用 REST API。它必須設定為用戶登入帳號（例如，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 參數附加到查詢網址來明確指定要包含在查詢結果中的關聯：

範例

要擷取帶有描述的問題日誌：

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`¶