共通仕様

このページでは、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

名前	型	説明
includes	string	取得対象となる関連オブジェクトのフィールド名をカンマ区切りの文字列で指定する。

名前	型	説明
fields	string	取得対象フィールドをカンマ区切りの文字列で指定する。

リクエスト

 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のユーザー権限が適用されます。

共通仕様

基本方針

取得 (GET)

追加 (POST)

更新 (PUT)

削除 (DELETE)

オブジェクトIDの指定

クエリパラメーター

名前指定

ソート

ソート関連パラメーター

削除済みデータの扱いを指定

削除データ関連パラメーター

ページネーション

ページネーション関連パラメーター

関連オブジェクトを指定して取得

関連オブジェクト指定用パラメーター

取得データに含まれるフィールドの指定

フィールド指定用パラメーター

アクションパラメーター

アクションパラメーターの一覧

レスポンス

データ形式

レスポンスにより取得するデータ

ステータスコード

エラーコード

型ごとの既定値

日付型の指定方法について

権限

基本方針​

取得 (GET)​

追加 (POST)​

更新 (PUT)​

削除 (DELETE)​

オブジェクトIDの指定​

クエリパラメーター​

名前指定​

ソート​

ソート関連パラメーター​

削除済みデータの扱いを指定​

削除データ関連パラメーター​

ページネーション​

ページネーション関連パラメーター​

関連オブジェクトを指定して取得​

関連オブジェクト指定用パラメーター​

取得データに含まれるフィールドの指定​

フィールド指定用パラメーター​

アクションパラメーター​

アクションパラメーターの一覧​

レスポンス​

データ形式​

レスポンスにより取得するデータ​

ステータスコード​

エラーコード​

型ごとの既定値​

日付型の指定方法について​

権限​

基本方針

取得 (GET)

追加 (POST)

更新 (PUT)

削除 (DELETE)

オブジェクトIDの指定

クエリパラメーター

名前指定

ソート

ソート関連パラメーター

削除済みデータの扱いを指定

削除データ関連パラメーター

ページネーション

ページネーション関連パラメーター

関連オブジェクトを指定して取得

関連オブジェクト指定用パラメーター

取得データに含まれるフィールドの指定

フィールド指定用パラメーター

アクションパラメーター

アクションパラメーターの一覧

レスポンス

データ形式

レスポンスにより取得するデータ

ステータスコード

エラーコード

型ごとの既定値

日付型の指定方法について

権限