kintone REST API は、kintone のアプリやレコード、スペースを操作できる API です。
このページでは、kintone REST API の共通仕様を説明します。
各 API の仕様の詳細は、それぞれの API のページを確認してください。
リクエスト
HTTP メソッド
API によって異なります。
URL
- 通常(ゲストスペース以外)
- https://sample.cybozu.com/k/v1/
リソース
- ゲストスペース
- https://sample.cybozu.com/k/guest/
スペースのID
/v1/リソース
リソース
は、API によって異なります。
詳細は各 API のページを確認してください。
リクエストヘッダー
送信するリクエストに応じて次のリクエストヘッダーを指定します。
kintone REST API リクエストを送信する API を使って、kintone REST API を実行する場合、リクエストヘッダーの指定は不要です。
ヘッダー名 | 必須 | 内容 |
---|---|---|
Host | 必須 | sample.cybozu.com:443 |
Content-Type | 条件必須 | リクエストボディを送信する場合のみ指定します。 指定する値はリクエストボディの形式によって異なります。
|
X-Cybozu-Authorization | 条件必須 | 「ログイン名:パスワード」を Base64 エンコードした値 パスワードを使って認証する場合は、必須です。 詳細は、 パスワード認証 を参照してください。 |
X-Cybozu-API-Token | 条件必須 | kintone の API トークン API トークンを使って認証する場合は必須です。 詳細は、 APIトークン認証 を参照してください。 |
Authorization | 条件必須 | 「Basic 」と「"Basic認証のユーザー名:Basic認証のパスワード" を Base64 エンコードした値」を結合した値 Basic 認証 を設定している場合、必須です。 詳細は、 Basic 認証を設定している環境 を参照してください。 |
X-HTTP-Method-Override | 省略可 | HTTP メソッド(GET/POST/PUT/DELETE) このヘッダーは、リクエスト URL が 8 KB を超えると発生する Request URL Too Large エラーを回避する目的で使用します。 「X-HTTP-Method-Override」に HTTP メソッドを指定して POST リクエストを送信すると、指定した HTTP メソッドに対応する API が実行されます。 以下は、ヘッダーを付けて レコードを複数取得する API を実行するときの例です。 curl -X POST https://sample.cybozu.com/k/v1/records.json \このヘッダーは、すべての kintone REST API で利用できますが、 外部の API を実行する API で実行した場合の動作はサポートしていません。 「X-HTTP-Method-Override」に指定する HTTP メソッドは、大文字を指定してください。 kintone REST API リクエストを送信する API で URL の長さが 4 KB を超える GET リクエストを送信した場合、「X-HTTP-Method-Override」ヘッダーが自動的に付与され、POST リクエストとして送信されます。 |
リクエストボディ
JSON 形式で指定します。文字コードは UTF-8 です。
ただし、
ファイルをアップロードする API はマルチパート形式で指定します。
JSON 文字列でエスケープが必要な文字は、\
でエスケープしてください。
クエリパラメーター
GET メソッドの API では、URL のクエリパラメーターとしてリクエストパラメーターを付与し、リクエストを送信できます。
たとえばリクエストパラメーターの app
が「1」の場合、クエリパラメーターは次のように指定します。
|
|
エスケープ
URL の仕様に従い、クエリパラメーターのキーや値はパーセントエンコーディングします。
以下は、クエリパラメーターの「更新日時 > "2021-10-01T09:00:00+0900"」をパーセントエンコーディングした例です。
|
|
配列型のパラメーターを指定する場合
配列を要素に分解してパーセントエンコーディングします。
リクエストパラメーターの fields
に、「レコード番号」と「ドロップダウン」を指定する例を示します。
-
fields=[レコード番号,ドロップボックス]
という配列を要素に分解します。1
/k/v1/records.json?app=1&fields[0]=レコード番号&fields[1]=ドロップダウン
-
クエリパラメーターのキーや値をパーセントエンコーディングします。
1
/k/v1/records.json?app=1&fields%5B1%5D=%e4%bd%9c%e6%88%90%e6%97%a5%e6%99%82&fields%5B2%5D=%e3%83%89%e3%83%ad%e3%83%83%e3%83%97%e3%83%80%e3%82%a6%e3%83%b3
レスポンス
HTTP ステータスコード
リクエストに成功した場合、200 番台のステータスコードが返ります。
リクエストに失敗した場合、200 番台以外のステータスコードと、次のプロパティをもつオブジェクトが返ります。
パラメーター名 | 型 | 説明 |
---|---|---|
id | 文字列 | エラー ID サポートへの問い合わせの際に利用します。 |
code | 文字列 | エラーの種類を表すコード |
message | 文字列 | エラーメッセージ API を実行するユーザーの表示言語の設定によって異なります。 |
エラーの例
|
|
レスポンスヘッダー
パラメーター名 | 型 | 説明 |
---|---|---|
X-ConcurrencyLimit-Limit | 数値 | 同時接続数の上限値 必ず 100 が返ります。 |
X-ConcurrencyLimit-Running | 数値 | 現在の同時接続数 |
kintone REST API リクエストを送信する API で実行した場合
kintone REST API リクエストを送信する API を使って、kintone REST API を実行した場合、コールバック関数に渡される情報は、リクエストボディのみです。
レスポンスボディ以外の情報を利用する場合には、
kintone REST API リクエストを送信する API 以外の方法で、kintone REST API を実行してください。
レスポンスボディ
JSON 形式で返されます。文字コードは UTF-8 です。
ただし、
ファイルをダウンロードする API では、バイナリデータが返されます。
日時のフォーマット
日時を扱うフィールドでは、次の形式の文字列を指定してください。
日付
- フォーマット
YYYY-MM-DD
- 補足
- 次の形式も許容されます。
YYYY
(例:2015)YYYY-MM
(例:2015-07)YYYY-M
(例:2015-7)YYYY-M-D
(例:2015-7-5)
- 月日を省略すると 01 で補完され、桁数が足りない場合は 0 埋めされます。
- 2015 → 2015-01-01
- 2015-07 → 2015-07-01
- 2015-7 → 2015-07-01
- 2015-7-5 → 2015-07-05
時刻
- フォーマット
HH:MM
- 補足
- UTC には変換されません。
日時(取得するとき)
- フォーマット
YYYY-MM-DDTHH:MM:SSZ
- 補足
- たとえば、日本時間(JST)の 2012 年 3 月 22 日 14 時 00 分は、「2012-03-22T05:00:00Z」と表します。
「YYYY-MM-DD」と「HH:MM:SS」の間の「T」や、「HH:MM:SS」の後ろの「Z」は固定値です。
「Z」は UTC を表します。 - 「T」以降を省略すると、UTC として扱われます。
- 一覧の設定を取得する API では、日時は UTC で出力されます。
日時(登録または更新するとき)
- フォーマット
YYYY-MM-DDTHH:MM:SS±HH:MM
またはYYYY-MM-DDTHH:MM:SSZ
- 補足
- たとえば、日本時間(JST)の 2012 年 3 月 22 日 14 時 17 分は、次のように表します。
「2012-03-22T14:17:00+09:00」「2012-03-22T05:17:00Z」 - 「YYYY-MM-DD」と「HH:MM:SS」の間の「T」や、「HH:MM:SS」の後ろの「Z」は固定値です。
- 「±HH:MM」には、UTC との時刻の差を指定します。
- 「T」以降を省略すると、UTC として扱われます。
- 秒情報を指定して登録または更新を行と、秒情報は無視されます。
たとえば、「2019-02-06T12:59:59Z」と指定すると、「2019-02-06T12:59:00Z」として登録または更新されます。
注意事項
- リクエストデータ、およびレスポンスデータの JSON フォーマットには、今後フィールドやキーなどが追加される場合があります。
- REST API を実行すると監査ログに記録されます。詳細は
kintoneの監査ログの確認方法/ログ一覧
を参照してください。
- 1 日に実行できる API は、1 つのアプリにつき 10,000 件までです。
リクエスト数にカウントされない API は、 1日に実行できるAPIリクエスト数を確認してください。
制限事項
同時接続数
同時にリクエストできる API は、1 ドメインにつき 100 までです。
レコードを操作する API
-
複数のレコードを取得する API の
offset
で指定できるレコードの上限数は、10,000 件までです。 - 一度に登録/更新/削除できるレコードは、100 件までです。
- 1 つのテーブルに大量の行を追加しないでください。
アプリの構成によっては負荷がかかり、レコードの表示や REST API を使った操作などのレコードの処理に影響します。
kintone の性能を考慮したレコードの操作方法は、 kintone の性能改善 を参照してください。 - 存在しないフィールドコードを指定して、レコードを取得/登録/更新した場合でも、存在しないフィールドコードは無視されて処理されます。
- 次のフィールドは、値の取得のみです。登録や更新はできません。
- ルックアップフィールドによって値が入力されるフィールド
- カテゴリー
- 計算
- ステータス
更新する場合は、 レコードのステータスを更新する API を使います。 - 作業者
更新する場合は、 レコードの作業者を更新する API を使います。
- レコードの登録や更新をする API でルックアップフィールドの値を変更する場合、ルックアップフィールドの「コピー元のフィールド」は、「レコード番号」フィールド、または「値の重複を禁止する」を設定したフィールドを指定してください。
- ルックアップフィールドの「コピー元のフィールド」に、自動計算を設定している「文字列 1 行」フィールドを選択している場合、ルックアップフィールドの値は変更できません。
ファイルをアップロードする API
アップロードしたファイルは、一時保管領域に保存されます。
レコードの登録や更新をする API でレコードに添付しない限り、3 日間で削除されます。
一時保管領域に保存したファイルは、ディスク使用量に含まれます。
レコードにコメントする API
一度に取得できるレコードのコメントは 10 件までです。
その他の制限事項
- kintone に関するその他の制限事項は、
制限値一覽
を確認してください。
- その他、サービスに関する制限事項は、
サイボウズのクラウドサービス制限事項
を確認してください。