共通仕様
このページでは、TimeTracker NX Web APIの共通仕様について紹介します。
基本方針
TimeTracker NX Web APIにおけるメソッド毎の共通的なふるまいは以下のとおりです。
取得 (GET)
URIに取得対象オブジェクトのIDを指定し、データを取得します。
複数のIDを指定した場合、指定したIDのデータが一つも存在しない場合にエラーになります。
いずれかのIDのデータが存在する場合はエラーになりません。
追加 (POST)
追加するデータをリクエストボディで指定します。
必須フィールドが指定されなかった場合はエラーになります。
任意のフィールドで未指定の場合は、既定値が適用されます。
更新 (PUT)
更新するデータをリクエストボディで指定します。
指定したフィールドのみ値が更新されます。
指定したIDのデータが存在しない場合はエラーになります。
削除 (DELETE)
URIのパスパラメーターに削除対象オブジェクトのIDを指定し、データを削除します。
指定したIDのデータが存在しない場合はエラーになります。
オブジェクトIDの指定
対象オブジェクト（データ）のIDをURI中で指定することにより、特定のオブジェクトに対する操作を実行します。
URIの定義中 {~Id} もしくは {~Ids} の部分が該当します。
例：指定したユーザーの実績工数を取得する
定義： GET /system/users/{userIds}/timeEntries
実行例： GET /system/users/10/timeEntries
{~Ids}の場合は、複数のIDを指定することが可能です。
その場合、対象オブジェクトのIDをカンマ区切りで指定します。
例：プロジェクト情報を取得する
定義： GET /project/projects/{projectIds}
実行例： GET /project/projects/120,121,122
対象オブジェクトを複数指定する（下位リソースが存在する）場合も、同様にそれぞれのIDを指定します。
例：指定したユーザーの特定の実績工数情報を取得する
定義： GET /system/users/{userIds}/timeEntries/{timeEntryIds}
実行例： GET /system/users/10/timeEntries/1000,1001
クエリパラメーター
クエリパラメーターとは、Web APIを実行する際に任意で追加可能なパラメーターです。
このパラメーターを使用することで、実行するAPIに様々な条件を追加することができます。
クエリパラメーターは、URIの末尾に「?」に続けて指定します。複数のクエリパラメーターを指定する場合は、「&」でつなぎます。
また、一覧取得のAPIにおいては、文字列 (string型) のクエリパラメーターに複数の値を指定することが可能です。
複数の値を指定する場合は、値と値を「,」でつなぎます。
名前指定
基本的には検索対象の値にはIDを指定しますが、名前など他の方法で指定できるパラメータもあります。
例）プロジェクト取得API
本APIでプロジェクトの管理者を指定する場合は、以下の3つの方法があります。
| No | 名前 | 説明 |
|---|---|---|
| 1 | managerIds | 取得対象の管理者ID |
| 2 | managerName | 管理者名 |
| 3 | managers | 取得対象とする管理者(複数条件からの 検索) |
No.1~3のうち、どれか1つで指定すれば該当する情報を取得できます。
No.2,3の方法であればIDを取得する処理は必要なく、直接名前を指定しても対象データを取得することができます。
（API呼び出し回数の削減にも繋がります。）
該当するパラメータは各APIのリファレンスをご参照ください。
- 同じ名前が複数ある場合はIDが小さい値を取得します。
- No.1とNo.2で異なるユーザーを指定した場合は、IDで指定したデータを取得します。
ソート
以下のパラメーターにより、取得(GET)のAPIにより取得したデータの並び順を指定することができます。
ソート関連パラメーター
| パラメーター | 型 | 説明 |
|---|---|---|
| orderby | string | 出力結果の並び順を指定します。ソート対象のフィールドの後ろに空白 (" ") を入れて指定します。 既定値は asc です。(asc: 昇順、desc: 降順) |
例：ユーザーの一覧情報をコードの降順で取得
GET /system/users?orderby=code desc
削除済みデータの扱いを指定
取得(GET)のAPIにより取得対象とするデータにおいて、以下のパラメーターにより削除済みデータの扱いを指定することができます。
削除データ関連パラメーター
| パラメーター | 型 | 説明 |
|---|---|---|
| includeDeleted | boolean | 削除済みデータを含めて取得するかどうかを指定します。 既定値は false です。(true: 含める、false: 含めない) |
| isDeleted | boolean | 削除済みデータのみ取得するかどうかを指定します。 includeDeleted が true の場合のみ指定可能です。 (true: 削除済みデータのみ、false:削除されていないデータのみ) |
例：ユーザーの一覧情報を取得（削除済みユーザーも含める）
GET /system/users?includeDeleted=true
ページネーション
データの一覧を取得するAPIにおいて、パフォーマンス向上のためにページネーションを活用することができます。
ページネーションは取得対象データの件数や何件目から取得するかを指定するもので、大量のデータを取得する際に特に有効です。
ページネーションに関するパラメーターは以下のとおりです。
ページネーション関連パラメーター
| パラメーター | 型 | 説明 |
|---|---|---|
| limit | int | データの最大取得件数を指定します。 |
| offset | int | 対象データのうち、何番目のデータから取得するかを指定します。 未指定の場合および0を指定した場合は、先頭のデータから取得します。。 0は先頭のデータを意味します。 |
例：指定ユーザーの実績工数一覧を取得する（10件目のデータから最大50件）
GET /system/users/10/timeEntries?limit=50&offset=9
関連オブジェクトを指定して取得
取得(GET)のAPIには、以下のパラメーターを利用して対象オブジェクトの取得結果に含まれる関連オブジェクトの範囲が指定できるものがあります。
関連オブジェクト指定用パラメーター
| 名前 | 型 | 説明 |
|---|---|---|
| includes | string | 取得対象となる関連オブジェクトのフィールド名をカンマ区切りの文字列で指定する。 |
例：プロジェクト情報を取得する（プロジェクトメンバを含める）
リクエスト
GET /project/projects/120?includes=Members
レスポンス
[
{
"name":"S機器の開発",
"code":"PRJ-002",
"managerId":"21",
.
.
.
// プロジェクトメンバの情報がレスポンスに追加されます。
"members":[
{"partyId":"14","name":"山本 博","englishName":"","partyType":"User",・・・},
{"partyId":"15","name":"藤井 智一","englishName":"","partyType":"User",・・・},
{"partyId":"17","name":"柴田 智彦","englishName":"","partyType":"User",・・・},
{"partyId":"21","name":"岡本 直哉","englishName":"","partyType":"User",・・・},
{"partyId":"23","name":"植田 信貴","englishName":"","partyType":"User",・・・},
{"partyId":"40","name":"黒川 悠太","englishName":"","partyType":"User",・・・}
],
}
]
取得データに含まれるフィールドの指定
取得(GET)のAPIでは、対象オブジェクトの取得結果に含まれるフィールドを指定することができます。
フィールドを指定する場合、以下のパラメーターをURIに追加します。
フィールド指定用パラメーター
| 名前 | 型 | 説明 |
|---|---|---|
| fields | string | 取得対象フィールドをカンマ区切りの文字列で指定する。 |
fieldsパラメーターが利用できるのは、workItemエリアの取得APIのみです。
例：ワークアイテム情報を取得する（指定フィールドのみ）
リクエスト
GET /workitem/workItems/1500?fields=name,plannedStartDate,plannedFinishDate,actualTime
レスポンス
[
{
// fieldsパラメータに指定したパラメータが取得されます
"fields": {
"Id": "1470075",
"Name": "仕様作成",
"PlannedStartDate": "2018-06-04T00:00:00",
"PlannedFinishDate": "2019-03-29T00:00:00",
"ActualTime": 28065,
}
}
]
アクションパラメーター
追加 (POST) や更新 (PUT) のAPIには、フィールド値に加えてオブジェクトの操作を指定することができるものがあります。
これはリクエストボディに記述するパラメーターで、アクションパラメーターと呼びます。
アクションパラメーターには、大別すると「関連オブジェクト操作」「移動」「復元」「その他」の3つに分類されます。
以下の種類のアクションパラメーターがあります。
アクションパラメーターの一覧
| API | 種別 | パラメーター | 説明 |
|---|---|---|---|
| プロジェクトの追加 | 関連オブジェクト操作 | userGroups | プロジェクト固有のユーザーグループを追加する |
| members | プロジェクトメンバを追加する | ||
| プロジェクトの更新 | 関連オブジェクト操作 | userGroupChange | プロジェクト固有のユーザーグループを更新する |
| memberChange | プロジェクトメンバを更新する | ||
| その他 | setLocked | 対象プロジェクトをロックする | |
| ワークアイテムの追加 | 移動 | orderBefore | 指定アイテムの直前に移動する |
| orderAfter | 指定アイテムの直後に移動する | ||
| orderFirst | 先頭に移動する | ||
| orderLast | 末尾に移動する | ||
| ワークアイテムの更新 | 移動 | orderBefore | 指定アイテムの直前に移動する |
| orderAfter | 指定アイテムの直後に移動する | ||
| orderFirst | 先頭に移動する | ||
| orderLast | 末尾に移動する | ||
| moveParentTo | 親アイテムを移動する | ||
| 復元 | restore | 削除したアイテムを復元する | |
| restoreToParent | 復元先の親アイテムを指定する | ||
| その他 | moveScheduleDays | スケジュールを更新する (子アイテムも含む) | |
| clearSchedule | スケジュールをクリアする (子アイテムも含む) | ||
| setCompleted | アイテムを「完了」にする (子アイテムも含む) | ||
| setTimeEntryLocked | 実績入力をロックする (子アイテムも含む) | ||
| changeItemTypeTo | アイテムタイプを変更する | ||
| clearAllFieldCalcTypes | フィールドの決定方法をデフォルトに戻す |
詳細は各APIのページをご覧ください。
例：プロジェクト情報更新時にユーザーグループを追加する
リクエスト PUT /project/projects/100
{
"name": "XXシステム開発",
"userGroupChange": {
"adds": [
{ "name": "設計チーム" },
{ "name": "実装チーム" }
]
}
}
レスポンス
{
"id": "100",
"addedUserGroupIds": ["21", "22"]
}
レスポンス
データ形式
TimeTracker NX Web APIでは、レスポンスはすべてJSON形式で返されます。
APIの種類により、レスポンスには以下の情報が含まれます。
| APIの種類 | レスポンスデータ |
|---|---|
| 取得(GET) | ステータスコード、取得したリソースのデータ |
| 追加(POST) | ステータスコード、追加されたリソースのID、追加対象以外で変更されたリソースのデータ |
| 更新(PUT) | ステータスコード、更新対象以外で変更されたリソースのデータ |
| 削除(DELETE) | ステータスコード、削除対象以外で変更されたリソースのデータ |
レスポンスの内容は各 API のリファレンスに記載しています。
プログラムを実行した結果、リファレンスに記載してされていないデータも返しますが、 未保証であるため、参照しないでください。
(リファレンスに記載されているデータのみ、保証しております)
レスポンスにより取得するデータ
TimeTracker NX からのレスポンスとして取得するデータは、各APIリファレンスのレスポンスの項目を参照してください。
レスポンスのデータは以下のパターンがあります。
-
単一データの場合
各リファレンスに記載した型のデータを返します。 -
複数データの場合
データを配列の形式で返します。
リファレンスでは型の後ろに『[]』を記載しています。
例）「ユーザーの取得」
-
一覧取得API の場合
条件に合致したデータに加え、totalCount として個数も返します。
取得したデータの中身（データ構造）は JSON形式のフォーマットに準拠しています。
ステータスコード
リクエストの処理結果を示すステータスコードは以下のとおりです。
| コード | 名前 | 説明 |
|---|---|---|
| 200 | OK | リクエストの処理が成功した。 |
| 400 | Bad Request | 無効なリクエストとしてリクエストが棄却された。 |
| 401 | Unauthorized | ユーザー認証に失敗し、リクエストが棄却された。 |
| 500 | Internal Server Error | サーバー内で問題が発生した。 |
エラーが発生した場合、エラー前のデータの状態に必ず戻る仕組みになっています。
データの破壊や中途半端な更新が起きることはありません。
エラーコード
Web API実行時にエラーが発生した場合に返されるエラーコードは以下のとおりです。
エラーコードは都度変更する可能性がございます。
| コード | 説明 |
|---|---|
| FieldCannotBeEmpty | フィールドに空の値が指定されている |
| FieldMustBeUnique | フィールドの値が一意でない |
| FieldOutOfRange | フィールドの値域を超えている |
| IdNotAvailable | 指定したIDのデータが利用できない |
| IdNotFound | 指定したIDのデータが削除されている、あるいは見つからない |
| InputTimeEntryAlwaysLocked | 実績入力が全期間ロックされている |
| InputTimeEntryLocked | 特定の日付以前の実績入力がロックされている |
| InvalidAssignment | プロジェクトのメンバーでないユーザーを指定した |
| InvalidCredentials | 認証情報が不正 |
| InvalidCurrentPassword | パスワードが現在のパスワードと一致しない |
| InvalidFormat | パラメータの形式が不正 |
| InvalidLicenseKey | ライセンスキーが不正 |
| InvalidParameter | パラメーターが不正 |
| LicenseExceeded | ライセンス数を超過している |
| LicenseExpired | ライセンスが無効 |
| NotMatchActualTimeUnit | 実績工数の入力粒度と異なる |
| NotMatchPlannedTimeUnit | 計画工数の入力粒度と異なる |
| OperationDenied | 実行時のエラーチェックで失敗した |
| PasswordMismatch | 新しいパスワードと確認用のパスワードが一致しない |
| ProjectLocked | プロジェクトがロックされている |
| SecurityError | セキュリティ権限エラー |
| TimeEntryOverlapped | 他の実績工数と重複する |
| WorkItemLocked | ワークアイテムの実績入力がロックされている |
| WorkItemNotAssigned | リソース割り当てがされてない |
型ごとの既定値
任意指定のパラメーターや、追加APIで任意指定のフィールドについて、個別の指定がないものの既定値は以下のとおりです。
| 型 | 既定値 |
|---|---|
| boolean | false |
| int | 0 |
| double | 0 |
| string | null |
| datetime | null |
日付型の指定方法について
更新日時など、TimeTrackerNX が自動的に記録する日時はすべて UTC とし、ISO 8601 に従って YYYY-MM-DDThh:mm:ssZ で返します。
YYYY-MM-DD と hh:mm:ss の間の T、hh:mm:ss の後ろの Z は固定値です。
指定例：2018年6月8日 4時56分40秒(UTC)の場合
"2018-06-08T04:56:40Z"
ユーザーがリクエストに指定する日時や日付は YYYY-MM-DDThh:mm:ss、YYYY-MM-DD の形式とし、タイムゾーンの変換は行う必要はありません。
日時の場合の T 以降は省略可能とし、省略した場合は YYYY-MM-DDT00:00:00 として扱います。
権限
Web APIを実行する際のTimeTracker NXの権限には、認証に使用したTimeTracker NXのユーザー権限が適用されます。