APIのはじめかた

このドキュメントではTimeTree APIの利用方法について説明します。

TimeTreeアカウントの登録

TimeTree APIを利用するために、TimeTreeのアカウントを登録してください。既にiOS/Android版を利用している場合はアプリから登録してください。

OAuthアプリケーションの登録

TimeTreeアカウントを作成したら、OAuthアプリケーションページに移動し、「アプリの作成」をクリックして必要な情報を入力してください。

パーソナルアクセストークンの発行

OAuthアプリケーションを作成する代わりにパーソナルアクセストークンを発行し、APIにリクエストすることもできます。

開発ガイドライン

すべてのアプリケーションはTimeTree開発者ガイドラインに従って実装されなければなりません。

クライアント

APIクライアントはHTTPSプロトコルを使って timetreeapis.com にリクエストしなければなりません。

データ形式

リクエスト・レスポンスは JSON:API に準拠したフォーマットを利用します。リクエストボディにJSONを含める場合は Content-Type ヘッダーを application/json に指定してください。日付を表現する場合は ISO8601 形式の文字列を利用します。

APIバージョン

すべてのAPIリクエストはv1バージョンとして取り扱われますが、 Accept ヘッダーで明示的に指定することを推奨します

Accept: application/vnd.timetree.v1+json

HTTPメソッド

Method Description
GET データを取得
POST データを作成
PUT データを更新
DELETE データを削除

HTTPステータス

成功

Status Description
200 OK リクエスト成功
201 Created リソースの作成に成功
204 No Content リクエストに成功(レスポンスボディなし)

失敗

クライアント失敗ステータス

Status Description
400 Bad Request 不正なリクエスト。 errors 等を参考にしてリクエストを修正してください
401 Unauthorized 認証されないリクエスト。アクセストークンがない、または不正なものになっています
403 Forbidden 許可されないリクエスト。アクセスできないリソースに対する操作が行われています
404 Not Found 指定したリソースが存在しない
406 Not Acceptable リクエストフォーマットが不正。jsonフォーマットを指定してください
429 Too Many Requests リクエスト制限。X-RateLimit-Reset ヘッダーで指定されるUnixタイムスタンプまでリクエストを待ってください

サーバー失敗ステータス

Status Description
500 Internal Server Error 不明なエラーが発生しています。サポートまで連絡ください
503 Service Unavailable APIサーバーが利用できない状態になっています
504 Timeout リクエストがタイムアウトしています。しばらく待ってリクエストしてください

リクエスト制限

TimeTree APIは 5000リクエスト/時間 のリクエスト制限を設けています。すべてのレスポンスのヘッダーでリクエスト制限の確認ができます。リクエスト制限はリクエスト元IP、アクセストークンごとにカウントされます。

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: 1556093863

エラーレスポンス

エラーメッセージは RFC7807 Problem Details for HTTP APIs に準拠したフォーマットです。 errors プロパティにエラーの詳細を記述したオブジェクトまたは文字列が追加される場合があります。

HTTP/1.1 404 Not Found
{
  "type": "about#blank",
  "status": 404,
  "title": "Not Found",
  "errors": "error detail(optional)"
}

認証

認証フロー

TimeTree APIではTimeTreeアカウントの認証・認可に OAuth2 を利用しています。TimeTreeのOAuth2関連のURLは https://timetreeapp.com/oauth/ になります。

  1. https://timetreeapp.com/oauth/authorize に以下のクエリパラメータでアクセスします。
Param Description
client_id アプリケーションのクライアントID。
redirect_uri 認証成功時にリダイレクトするURI。
response_type リクエストのレスポンスタイプ。TimeTree APIでは code のみサポートしています。
state リクエストの状態を管理する文字列。CSRF対策として付与することを推奨します。
code_challenge (オプション) PKCE 用のパラメーター。code_verifier から生成した文字列。
code_challenge_method (オプション) PKCE 用のパラメーター。S256 を推奨。
GET https://timetreeapp.com/oauth/authorize?client_id={client_id}&response_type=code&state={csrf_token}
  1. TimeTreeは redirect_uri で指定したURIに code パラメータを付与してリダイレクトします。ここで付与する code パラメーターの有効期限は 10分 です。
GET {redirect_uri}?code={code}&state={csrf_token}
  1. https://timetreeapp.com/oauth/token に以下のパラメーターをJSONボディに付与してアクセストークンのリクエストをします。
Param Description
client_id アプリケーションのクライアントID
client_secret アプリケーションのシークレット
redirect_uri アプリケーションのリダイレクトURI
code 上記フローで取得した code
grant_type authorization_code のみ有効
code_verifier (オプション) 上記1のフローで PKCE のパラメータを付与した場合に必須。 code_challenge を生成するために使用した文字列。
POST https://timetreeapp.com/oauth/token

アクセストークンのリクエストが成功した場合はアクセストークンが含まれたJSONレスポンスが返却されます。

{
  "acess_token": "ACCESS_TOKEN",
  "created_at": 1558583443,
  "token_type": "Bearer"
}
  1. 取得したアクセストークンは、APIリクエストの際に Authorization ヘッダーにBearerトークンとして含める必要があります。
Authorization: Bearer ACCESS_TOKEN

パーソナルアクセストークンによる認証

パーソナルアクセストークンを発行し、 Authorization ヘッダーにBearerトークンとして付与することでOAuthによる認証と同様にAPIリクエストを送信することができます。

Authorization: Bearer PERSONAL_ACCESS_TOKEN

ユーザー

GET /user

アクセストークンによって認可したユーザー(カレントユーザー)の情報を取得します。

Parameters

なし

Curl Example

$ curl https://timetreeapis.com/user \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 200 OK
{
  "data": {
    "id":  "12345",
    "type": "user",
    "attributes": {
      "name": "Your Name",
      "description": "blah blah blah",
      "image_url": "https://attachments.timetreeapp.com/path/to/image.png"
    }
  }
}

カレンダー

GET /calendars

カレントユーザーがアクセスできるカレンダーの一覧情報を取得します。

Parameters

Parameter Description
include 関連オブジェクトをレスポンスに含める。, 区切りで複数渡すことができる。labelsmembers のみサポート。オプション

Curl Example

$ curl https://timetreeapis.com/calendars?include=labels,members \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 200 OK
{
  "data": [
    {
      "id":  "1234",
      "type": "calendar",
      "attributes": {
        "name": "Some Calendar1",
        "description": "Calendar description",
        "color": "#2ecc87",
        "image_url": "https://attachments.timetreeapp.com/path/to/image.png",
        "created_at": "2019-04-01T12:34:56.000Z"
      },
      "relationships": {
        "labels": {
          "data": [
            { "id": "1234,1", "type": "label" },
            // ...
            { "id": "1234,10", "type": "label" }
          ]
        },
        "members": {
          "data": [
            { "id": "1234,12345", "type": "user" },
            { "id": "1234,23456", "type": "user" }
          ]
        }
      }
    },
    {
      "id":  "5678",
      "type": "calendar",
      "attributes": {
        "name": "Some Calendar2",
        "description": "Calendar description",
        "color": "#2ecc87",
        "image_url": "https://attachments.timetreeapp.com/path/to/image.png",
        "created_at": "2019-04-01T12:34:56.000Z"
      },
      "relationships": {
        // ...
      }
    }
  ],
  "included": [
    {
      "id": "1234,1",
      "type": "label",
      "attributes": {
        "name": "label title(empty if default)",
        "color": "#2ecc87"
      }
    },
    // ...
    {
      "id": "1234,12345",
      "type": "user",
      "attributes": {
        "name": "User1",
        "description": "blah blah blah",
        "image_url": "https://attachments.timetreeapp.com/path/to/image.png"
      }
    },
    // ...
  ]
}

GET /calendars/:calendar_id

指定したカレンダーの情報を取得します。

Parameters

Parameter Description
calendar_id カレンダーID。必須
include 関連オブジェクトをレスポンスに含める。, 区切りで複数渡すことができる。labelsmembers のみサポート。オプション

Curl Example

$ curl https://timetreeapis.com/calendars/1234?include=labels,members \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 200 OK
{
  "data": {
    "id":  "1234",
    "type": "calendar",
    "attributes": {
      "name": "Some Calendar",
      "description": "Calendar description",
      "color": "#2ecc87",
      "image_url": "https://attachments.timetreeapp.com/path/to/image.png",
      "created_at": "2019-04-01T12:34:56.000Z"
    },
    "relationships": {
      "labels": {
        "data": [
          { "id": "1234,1", "type": "label" },
          { "id": "1234,2", "type": "label" },
          { "id": "1234,3", "type": "label" },
          { "id": "1234,4", "type": "label" },
          { "id": "1234,5", "type": "label" },
          { "id": "1234,6", "type": "label" },
          { "id": "1234,7", "type": "label" },
          { "id": "1234,8", "type": "label" },
          { "id": "1234,9", "type": "label" },
          { "id": "1234,10", "type": "label" }
        ]
      },
      "members": {
        "data": [
          { "id": "1234,12345", "type": "user" },
          { "id": "1234,23456", "type": "user" }
        ]
      }
    }
  },
  "included": [
    {
      "id": "1234,1",
      "type": "label",
      "attributes": {
        "name": "label title(empty if default)",
        "color": "#2ecc87"
      }
    },
    // ...
    {
      "id": "1234,12345",
      "type": "user",
      "attributes": {
        "name": "User1",
        "description": "blah blah blah",
        "image_url": "https://attachments.timetreeapp.com/path/to/image.png"
      }
    },
    // ...
  ]
}

GET /calendars/:calendar_id/labels

指定したカレンダーの予定で使われるラベル情報を取得します。

Parameters

Parameter Description
calendar_id カレンダーID。必須

Curl Example

$ curl https://timetreeapis.com/calendars/1234/lables \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": "1234,1",
      "type": "label",
      "attributes": {
        "name": "label title(empty if default)",
        "color": "#2ecc87"
      }
    },
    {
      "id": "1234,2",
      "type": "label",
      "attributes": {
        "name": "label title(empty if default)",
        "color": "#3dc2c8"
      }
    },
    // ...
  ]
}

GET /calendars/:calendar_id/members

指定したカレンダーに参加しているユーザーの情報を取得します。

Parameters

Parameter Description
calendar_id カレンダーID。必須

Curl Example

$ curl https://timetreeapis.com/calendars/1234/members \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": "1234,12345",
      "type": "user",
      "attributes": {
        "name": "User1",
        "description": "blah blah blah",
        "image_url": "https://attachments.timetreeapp.com/path/to/image.png"
      }
    },
    {
      "id": "1234,56789",
      "type": "user",
      "attributes": {
        "name": "User2",
        "description": "Foo Bar",
        "image_url": "https://attachments.timetreeapp.com/path/to/anothor_image.png"
      }
    },
    // ...
  ]
}

予定・キープ

GET /calendars/:calendarid/events/:eventid

指定したカレンダーの特定の予定情報を取得します

Parameters

Parameter Description
calendar_id カレンダーID。必須
event_id 予定のID。必須
include 関連オブジェクトをレスポンスに含める。, 区切りで複数渡すことができる。creatorlabelattendees のみサポート。オプション

Curl Example

$ curl https://timetreeapis.com/calendars/1234/events/c9c8e0fd66c34505a876d88cb4bb3b2a?include=creator,label,attendees \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 200 OK
{
  "data": {
    "id": "c9c8e0fd66c34505a876d88cb4bb3b2a",
    "type": "event",
    "attributes": {
      "category": "schedule",
      "title": "Event title",
      "all_day": false,
      "start_at": "2019-03-18T09:00:00.000Z",
      "start_timezone": "UTC",
      "end_at": "2019-03-18T10:00:00.000Z",
      "end_timezone": "UTC",
      "recurrences": [],
      "description": "blah blah blah",
      "location": "Tokyo",
      "url": "https://example.com",
      "updated_at": "2019-03-18T09:53:33.123Z",
      "created_at": "2019-03-18T09:53:33.123Z"
    },
    "relationships": {
      "creator": {
        "data": {
          "id": "1234,12345",
          "type": "user"
        }
      },
      "label": {
        "data": {
          "id": "1234,1",
          "type": "label"
        }
      },
      "attendees": {
        "data": [
          { "id": "1234,12345", "type": "user" },
          { "id": "1234,56789", "type": "user" }
        ]
      }
    }
  }
}

POST /calendars/:calendar_id/events

カレンダーに予定を追加します

Parameters

Parameter Description
calendar_id カレンダーID。必須
data:attributes:title 予定のタイトル。最大50文字。必須
data:attributes:category 予定・キープを指定。scheduleまたはkeep。必須
data:attributes:all_day 終日予定。schedule: 必須、keep: オプション
data:attributes:start_at 開始時刻(ISO8601)。終日予定の場合は時刻を 00:00:00 にする必要があります。schedule: 必須、keep: オプション
data:attributes:start_timezone 開始時刻のタイムゾーン。オプション
data:attributes:end_at 終了時刻(ISO8601)。終日予定の場合は時刻を 00:00:00 にする必要があります。start_at より後の時刻を指定。schedule: 必須、keep: オプション
data:attributes:end_timezone 終了時刻のタイムゾーン。オプション
data:attributes:description 説明(ノート)。最大10000文字。オプション
data:attributes:location 場所。最大100文字。オプション
data:attributes:url URL。オプション
data:relationships:label:data:id 予定のラベルID。必須
data:relationships:label:data:type label のみ。必須
data:relationships:attendees:data[]:id 予定参加者のユーザーID。オプション
data:relationships:attendees:data[]:type user のみ。data:relationships:attendees:data[]:id がある場合必須

Curl Example

$ curl https://timetreeapis.com/calendars/1234/events \
  -d '{
    "data": {
      "attributes": {
        "category": "schedule",
        "title": "Event title",
        "all_day": false,
        "start_at": "2019-03-18T09:00:00.000Z",
        "start_timezone": "UTC",
        "end_at": "2019-03-18T10:00:00.000Z",
        "end_timezone": "UTC",
        "description": "blah blah blah",
        "location": "Tokyo",
        "url": "https://example.com"
      },
      "relationships": {
        "label": {
          "data": {
            "id": "1234,1",
            "type": "label"
          }
        },
        "attendees": {
          "data": [
            { "id": "1234,12345", "type": "user" },
            { "id": "1234,56789", "type": "user" }
          ]
        }
      }
  }' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 201 Created
{
  "data": {
    "id": "c9c8e0fd66c34505a876d88cb4bb3b2a",
    "type": "event",
    "attributes": {
      "category": "schedule",
      "title": "Event title",
      "all_day": false,
      "start_at": "2019-03-18T09:00:00.000Z",
      "start_timezone": "UTC",
      "end_at": "2019-03-18T10:00:00.000Z",
      "end_timezone": "UTC",
      "recurrences": [],
      "description": "blah blah blah",
      "location": "Tokyo",
      "url": "https://example.com",
      "updated_at": "2019-03-18T09:53:33.123Z",
      "created_at": "2019-03-18T09:53:33.123Z"
    },
    "relationships": {
      "creator": {
        "data": {
          "id": "1234,12345",
          "type": "user"
        }
      },
      "label": {
        "data": {
          "id": "1234,1",
          "type": "label"
        }
      },
      "attendees": {
        "data": [
          { "id": "1234,12345", "type": "user" },
          { "id": "1234,56789", "type": "user" }
        ]
      }
    }
  }
}

PUT /calendars/:calendarid/events/:eventid

カレンダーの予定を更新します

Parameters

Parameter Description
calendar_id カレンダーID。必須
event_id 予定のID。必須
data:attributes:title 予定のタイトル。最大50文字。必須
data:attributes:category 予定・キープを指定。scheduleまたはkeep。必須
data:attributes:all_day 終日予定。schedule: 必須、keep: オプション
data:attributes:start_at 開始時刻(ISO8601)。終日予定の場合は時刻を 00:00:00 にする必要があります。schedule: 必須、keep: オプション
data:attributes:start_timezone 開始時刻のタイムゾーン。オプション
data:attributes:end_at 終了時刻(ISO8601)。終日予定の場合は時刻を 00:00:00 にする必要があります。start_at より後の時刻を指定。schedule: 必須、keep: オプション
data:attributes:end_timezone 終了時刻のタイムゾーン。オプション
data:attributes:description 説明(ノート)。最大10000文字。オプション
data:attributes:location 場所。最大100文字。オプション
data:attributes:url URL。オプション
data:relationships:label:data:id 予定のラベルID。必須
data:relationships:label:data:type label のみ。必須
data:relationships:attendees:data[]:id 予定参加者のユーザーID。オプション
data:relationships:attendees:data[]:type user のみ。data:relationships:attendees:data[]:id がある場合必須

Curl Example

$ curl -X PUT https://timetreeapis.com/calendars/1234/events/c9c8e0fd66c34505a876d88cb4bb3b2a \
  -d '{
    "data": {
      "attributes": {
        "category": "schedule",
        "title": "Event title",
        "all_day": false,
        "start_at": "2019-03-18T09:00:00.000Z",
        "start_timezone": "UTC",
        "end_at": "2019-03-18T10:00:00.000Z",
        "end_timezone": "UTC",
        "description": "blah blah blah",
        "location": "Tokyo",
        "url": "https://example.com"
      },
      "relationships": {
        "label": {
          "data": {
            "id": "1234,1",
            "type": "label"
          }
        },
        "attendees": {
          "data": [
            { "id": "1234,12345", "type": "user" },
            { "id": "1234,56789", "type": "user" }
          ]
        }
      }
  }' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 200 OK
{
  "data": {
    "type": "event",
    "id": "c9c8e0fd66c34505a876d88cb4bb3b2a",
    "attributes": {
      "category": "schedule",
      "title": "Event title",
      "all_day": false,
      "start_at": "2019-03-18T09:00:00.000Z",
      "start_timezone": "UTC",
      "end_at": "2019-03-18T10:00:00.000Z",
      "end_timezone": "UTC",
      "recurrences": [],
      "description": "blah blah blah",
      "location": "Tokyo",
      "url": "https://example.com",
      "updated_at": "2019-03-18T09:53:33.123Z",
      "created_at": "2019-03-18T09:53:33.123Z"
    },
    "relationships": {
      "author": {
        "data": {
          "id": "1234,12345",
          "type": "user"
        }
      },
      "label": {
        "data": {
          "id": "1234,1",
          "type": "label"
        }
      },
      "attendees": {
        "data": [
          { "id": "12345", "type": "user" },
          { "id": "56789", "type": "user" }
        ]
      }
    }
  }
}

DELETE /calendars/:calendarid/events/:eventid

カレンダーの予定を削除します。

Parameters

Parameter Description
calendar_id カレンダーID。必須
event_id 予定のID。必須

Curl Example

$ curl -X DELETE https://timetreeapis.com/calendars/1234/events/c9c8e0fd66c34505a876d88cb4bb3b2a \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 204 No Content

コメント

POST /calendars/:calendarid/events/:eventid/activities

予定にコメントを投稿します。

Parameters

Parameter Description
calendar_id カレンダーID。必須
event_id 予定のID。必須
data:attributes:content コメントテキスト。最大1000文字。必須

Curl Example

$ curl -X POST https://timetreeapis.com/calendars/1234/events/c9c8e0fd66c34505a876d88cb4bb3b2a/activities \
  -d '{
    "data": {
      "attributes": {
        "content": "This is comment"
      }
    }
  }' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.timetree.v1+json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response Example

HTTP/1.1 201 Created
{
  "data": {
    "id": "5fde58f529bf4359b6cc15523ed86965",
    "type": "activity",
    "attributes": {
      "content": "This is comment",
      "updated_at": "2019-04-01T12:34:56.000Z",
      "created_at": "2019-04-01T12:34:56.000Z"
    }
  }
}