redmineAPIまとめ
redmineでプロジェクトを跨いだチケットを一括発行したり、複数プロジェクトを取得し、一覧で閲覧できるツールが作りたかった為、それに必要そうなAPIの仕様を纏めました。
概要
- version 3.4.4
- REST API
- 返却値としてはxml,jsonが選択できる
- コールの際はAPIKEYが必須
- 公式wiki
共通
APIをコールする際
APIをコールする場合には必ずkeyかログインID/PWを送る必要がある
keyを送る場合
- パラメータにkeyを入れる
- HTTPヘッダーにX-Redmine-API-KeyにAPIKEYを追加して送る
ID/PWを使う場合
- Basic認証
POST/PUTのリクエストを送る場合
Content-Typeを必ずリクエストヘッダーに追加して送る
JSONの場合
Content-Type: application/json
XMLの場合
Content-Type: application/xml
GETリクエストを送る場合
デフォルトでは25件しか取得されない
返却値には内容、全件数、取得数、取得位置が含まれている
limitの最大は100
100件以上やページングしたい場合はoffsetを変更して取得していく
<issues type="array" total_count="2595" limit="25" offset="0">
...
</issues>
{ "issues":[...], "total_count":2595, "limit":25, "offset":0 }
カスタムフィールドを使用する場合
redmineではカスタムフィールドを設定できる。
これは返却値のcustom_fieldsに格納される。
{"issue":
{
"id":777,
...
"custom_fields":
[
{"value":"testvalue","name":"custom_field1","id":1},
{"value":"customField","name":"custom_field2","id":2}
]
}
}
関連データも取得する場合
includeパラメータに対応する値を付けることで関連データを取得することができる。
includeに付与できる値は以下
children //子チケット
attachments //添付ファイル
relations //関連するチケット
changesets //リポジトリのチェンジセット
journals //履歴
trackers //トラッカー一覧
time_entry_activities //作業、開発時間
enabled_modules //有効なモジュールのリスト
GET /issues/1.json?include=journals
ファイルを送る場合
redmineでチケットに添付ファイルを登録する場合は、ファイル登録→チケット登録の順で行う必要がある。
ファイル登録
URL
POST /uploads.json
ヘッダー
Content-Type: application/octet-stream
ボディ
アップロードしたいファイルを設定
登録に成功した場合
201レスポンス
{"upload":{"token":"7167.ed1ccdb093229ca1bd0b043618d88743"}}
登録に失敗した場合
422レスポンス
チケット登録
ファイル登録成功時に返ってくるトークンをボディに含んで送ることで添付できる
URL
POST/issues.json
{
"issue": {
"project_id": "1",
"subject": "uploadfile",
"uploads": [
{"token": "hwaiudhiowjdaodhwauihdoiahdoh", "filename": "image.png", "content_type": "image/png"}
]
}
}
複数件添付する場合はuploadsに対象分記載すればOK
チケット
一覧の取得
GET /issues.[format]
ページングされたチケットのリストが返却される。デフォルトでは未完了のチケットのみ返却される。
パラメータ
共通
- offset
- limit
- page
- sort
- include (関連するデータを取得するを参照)
フィルター
- project_id (名前では無く数字を入れる)
- subproject_id (
project_id=XXX&subproject_id=!*でそのプロジェクトに属する全てのチケットが取得可能) - tracker_id (num)
- status_id (
open,close,*が使用可能) - assigned_to_id (担当者ID)
- parent_id (親チケットID)
- cf_x (xにはカスタムフィールドIDを入れる)
JSON形式のレスポンス例
{
"issues":[{
"id":123,
"project":{
"id":1,
"name":"プロジェクト"
},
"tracker":{
"id":1,
"name":"トラッカー"
},
"status":{
"id":1,
"name":"新規"
},
"priority":{
"id":1,
"name":"新規"
},
"author":{
"id": 1,
"name":"ユーザ１"
},
"assigned_to":{
"id": 2,
"name":"ユーザ２"
},
"fixed_version":{
"id":1,
"name":"テスト"
},
"subject":"題名",
"description":"説明",
"start_date":"2018-06-25",
"due_date":"2018-06-27",
"custom_fields":[
{
"id":1,
"name":"カスタムフィールド１",
"value":"custom_field1"
},
...
],
...,
...,
}],
"total_count":1000,
"offset":0,
"limit":25
}
表示
GET /issues/[id].[format]
一覧と同じようなものだが、指定できるパラメータが違う
パラメータ
- children (子チケット)
- attachments (添付ファイル)
- relations (関連するチケット)
- changesets (リポジトリのチェンジセット)
- journals (履歴)
- watchers (ウォッチャー)
作成
POST /issues.[format]
パラメータを指定しないとおそらくデフォルト値が入る
作成に成功すると作成したチケットのIDが返却される
設定できる要素
- project_id (作成先のプロジェクト:num)
- tracker_id (トラッカー:num)
- status_id (ステータス:num)
- priority_id (優先度:num)
- subject (題名)
- description (説明)
- start_date (開始日:DATE)
- due_date (終了日:DATE)
- parent_id (親チケットID)
- assigned_to_id (担当者ID)
- fixed_version_id (対象バージョンID)
その他も設定できるはず、チケットを取得して要素を見るべし(あるステータスならだいたい送れる)*参考
作成成功時のJSON
{
"issue":{
"id":1234,
"project":{
"id":1
"name":"プロジェクト"
},
...,
...,
}
}
idに作成したチケットのIDが格納されている。
それ以外は指定した項目かデフォルト値が入る。
更新
PUT /issues/[id].[format]
更新したいチケットIDに対して要素を指定しPUTリクエスト
成功したらレスポンス200
削除
DELETE /issues/[id].[format]
削除したいチケットIDに対してDELETEリクエストを送るだけ
成功したらレスポンス200
プロジェクト
一覧の取得
GET /projects.[format]
全てのプロジェクトを取得する(公開されているプロジェクトと自身が閲覧できる限定プロジェクトが対象)
パラメータ
- include (関連するデータを取得するを参照)
JSON形式でのレスポンス例
{
"projects":[
{
"id": 1,
"name":"プロジェクト",
"identifier":"",
"description":"",
"status":1,
"custom_fields":[
{
"id":1,
"name":"customField",
"value":""
}
],
"created_on":"2018-06-20T06:00:00Z",
"updated_on":"2018-06-20T06:00:00Z"
},
...,
...
],
"total_count":50,
"offset":0,
"limit":25
}
表示
GET /projects/[id].[format]
一覧表示と同じ
ユーザ(プロジェクトメンバー)
GET /projects/[id]/memberships.[format]
プロジェクトに所属しているメンバーの情報を取得する。
JSON形式でのレスポンス例
{
"memberships":[
{
"id":1,
"project":{
"id":1,
"name":"プロジェクト名"
},
"user":{
"id":1,
"name":"テストユーザ"
},
"roles":[
{
"id":1,
"name":"ロール名"
},
...,
...,
]
},...,
],
"total_count":50,
"offset":0,
"limit":25
}
ユーザ(APIをコールしたユーザ)
GET /users/current.xml
JSON形式でのレスポンス例
{
"users":[
{
"id":1,
"login":"user",
"firstname":"テスト",
"lastname":"ユーザ",
"mail":"test@testuser.co.jp",
"created_on":"2018-06-20T06:00:00Z",
"last_login_on":"2018-06-20T06:00:00Z",
"api_key":"dwaiuhdwoakdjopkwajodijapw",
"custom_fields":[
{
"id":1,
"name":"test",
"value":""
}
]
}
]
}
APIをコールした人の情報が返ってくる
トラッカー
GET /trackers.xml
全てのトラッカー情報が返ってくるが・・・
GET /projects/[id].[format]?include=trackers
これでコールすれば対象プロジェクトのトラッカーが取得できるのでこちらの方が・・・
バージョン
GET /projects/[id]/versions.[format]
プロジェクトに紐づくバージョン一覧を取得できる