redmineAPIメモ

# redmineAPIまとめ

redmineでプロジェクトを跨いだチケットを一括発行したり、複数プロジェクトを取得し、一覧で閲覧できるツールが作りたかった為、それに必要そうなAPIの仕様を纏めました。


## 概要

* version 3.4.4
* REST API
* 返却値としてはxml,jsonが選択できる
* コールの際はAPIKEYが必須
* [公式wiki](http://www.redmine.org/projects/redmine/wiki/Rest_api)

---

## 共通

### 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を変更して取得していく

~~~xml:return.xml
<issues type="array" total_count="2595" limit="25" offset="0">
  ...
</issues>
~~~

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

### カスタムフィールドを使用する場合

redmineではカスタムフィールドを設定できる。
これは返却値の`custom_fields`に格納される。

~~~json:custom.json
{"issue":
  {
    "id":777,
    ...
    "custom_fields":
      [
        {"value":"testvalue","name":"custom_field1","id":1},
        {"value":"customField","name":"custom_field2","id":2}
      ]
  }
}
~~~

### 関連データも取得する場合

includeパラメータに対応する値を付けることで関連データを取得することができる。

includeに付与できる値は以下

~~~php:params
children    //子チケット
attachments //添付ファイル
relations   //関連するチケット
changesets  //リポジトリのチェンジセット
journals    //履歴
trackers     //トラッカー一覧
time_entry_activities //作業、開発時間
enabled_modules //有効なモジュールのリスト
~~~

~~~url:example
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`

~~~json:issues.json
{
  "issue": {
    "project_id": "1",
    "subject": "uploadfile",
    "uploads": [
      {"token": "hwaiudhiowjdaodhwauihdoiahdoh", "filename": "image.png", "content_type": "image/png"}
    ]
  }
}
~~~

複数件添付する場合はuploadsに対象分記載すればOK  

[content_typeの参照](https://developer.mozilla.org/ja/docs/Web/HTTP/Basics_of_HTTP/MIME_types)

---

## チケット

### 一覧の取得

`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形式のレスポンス例*

~~~json:issues.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_

~~~json:issues.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形式でのレスポンス例_

~~~JSON:projects.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形式でのレスポンス例_

~~~json:projects_member
{
  "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形式でのレスポンス例_

~~~json:current.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]`

プロジェクトに紐づくバージョン一覧を取得できる

---