kintone REST APIの共通仕様

目次

kintone REST APIは、kintoneのアプリやレコード、スペースを操作できるAPIです。
このページでは、kintone REST APIの共通仕様を説明します。
各APIの仕様の詳細は、それぞれのAPIのページを確認してください。

リクエスト

HTTPメソッド

APIによって異なります。

URL

RESOURCEは、APIによって異なります。
詳細は各APIのページを確認してください。

通常(ゲストスペース以外)
https://sample.cybozu.com/k/v1/RESOURCE
ゲストスペース
https://sample.cybozu.com/k/guest/SPACE_ID/v1/RESOURCE

リクエストヘッダー

送信するリクエストに応じて次のリクエストヘッダーを指定します。
kintone REST APIリクエストを送信するAPI(kintone.api())を使って、kintone REST APIを実行する場合、リクエストヘッダーの指定は不要です。
kintone REST APIリクエストを送信するAPI

Host

Garoon REST APIを実行するドメインとポート番号(443)を、「ドメイン:ポート番号」の形式で指定します。
Hostは必須です。

Content-Type

指定する値はリクエストボディの形式によって異なります。

  • JSON文字列の場合:application/json
  • マルチパートの場合:multipart/form-data

リクエストボディを送信する場合のみ指定します。

X-Cybozu-Authorization

「ログイン名:パスワード」をBase64エンコードした値を指定します。
パスワードを使って認証する場合のみ指定します。
パスワード認証の詳細は、次のページを参照してください。
パスワード認証

X-Cybozu-API-Token

kintoneのAPIトークンを指定します。
APIトークンを使って認証する場合のみ指定します。
APIトークン認証の詳細は、次のページを参照してください。
APIトークン認証

X-Requested-With

「XMLHttpRequest」または空文字列以外の文字列を指定します。
セッションで認証する場合のみ指定します。
セッション認証の詳細は、次のページを参照してください。
セッション認証

Authorization

次の値を半角スペースで結合した値を指定します。

  • Basic
  • 「Basic認証のユーザー名:Basic認証のパスワード」をBase64エンコードした値

Basic認証を設定している場合のみ指定します。
Basic認証を設定している環境でのリクエスト方法は、次のページを参照してください。
Basic認証を設定している環境

X-HTTP-Method-Override

実行するAPIのHTTPメソッド(GET/POST/PUT/DELETEのいずれか)を大文字で指定します。
このヘッダーにHTTPメソッドを指定してPOSTリクエストを送信すると、指定したHTTPメソッドに対応するAPIが実行されます。

リクエストURLが8KBを超える場合に指定すると、Request URL Too Largeエラーを回避できます。

たとえば、次のリクエスト例はレコードを複数取得するAPIを実行できます。

1
2
3
4
5
curl -X POST https://sample.cybozu.com/k/v1/records.json \
  -H 'X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=' \
  -H 'Content-Type: application/json'  \
  -H 'X-HTTP-Method-Override: GET' \
  -d '{ "app": 1, "query": "更新日時 > \"2012-02-03T09:00:00Z\"" }'

このヘッダーは、すべてのkintone REST APIで利用できます。
ただし、外部のAPIを実行するAPIでkintone REST APIを実行したときの動作はサポートしていません。
外部のAPIを実行する

Accept-Language

cybozu.comで利用できる表示言語の言語コードを指定します。
表示言語が「Webブラウザーの設定に従う」の場合、このヘッダーで指定した言語がレスポンスボディの言語に反映されます。

リクエスト結果の表示言語を指定したい場合のみ指定します。

リクエストボディ

JSON形式で指定します。文字コードはUTF-8です。
ただし、ファイルをアップロードするAPIはマルチパート形式で指定します。
ファイルをアップロードするAPI

JSON文字列でエスケープが必要な文字は、\でエスケープしてください。

クエリパラメーター

GETメソッドのAPIでは、URLのクエリパラメーターとしてリクエストパラメーターを付与し、リクエストを送信できます。
たとえばリクエストパラメーターのappが「1」の場合、クエリパラメーターは次のように指定します。

1
/k/v1/records.json?app=1
エスケープ

URLの仕様に従い、クエリパラメーターのキーや値はパーセントエンコーディングします。
以下は、クエリパラメーターの「更新日時 > "2021-10-01T09:00:00+0900"」をパーセントエンコーディングした例です。

1
/k/v1/records.json?app=1&query=%e6%9b%b4%e6%96%b0%e6%97%a5%e6%99%82%20%3E%20%222021-10-01T09%3A00%3A00%2B0900%22%20
配列型のパラメーターを指定する場合

配列を要素に分解してパーセントエンコーディングします。

リクエストパラメーターのfieldsに、「レコード番号」と「ドロップダウン」を指定する例を示します。

  1. fields=[レコード番号,ドロップボックス]という配列を要素に分解します。

    1
    
    /k/v1/records.json?app=1&fields[0]=レコード番号&fields[1]=ドロップダウン
  2. クエリパラメーターのキーや値をパーセントエンコーディングします。

    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番台以外のステータスコードとエラーレスポンスが返ります。
エラーレスポンス

レスポンスヘッダー

X-ConcurrencyLimit-Limit

同時接続数の上限値です。
必ず100が返ります。

X-ConcurrencyLimit-Running

現在の同時接続数です。

kintone REST APIリクエストを送信するAPIで実行した場合

kintone REST APIリクエストを送信するAPIを使って、kintone REST APIを実行した場合、コールバック関数に渡される情報は、レスポンスボディだけです。
レスポンスボディ以外の情報を利用する場合には、kintone REST APIリクエストを送信するAPI(kintone.api())以外の方法で、kintone REST APIを実行してください。
kintone REST APIリクエストを送信するAPI

レスポンスボディ

JSON形式で返されます。文字コードはUTF-8です。
ただし、ファイルをダウンロードするAPIでは、バイナリデータが返されます。
ファイルをダウンロードするAPI

エラーレスポンス

次のプロパティをもつオブジェクトがJSON形式で返されます。

パラメーター名 説明
id 文字列 エラーID
サポートへの問い合わせの際に利用します。
code 文字列 エラーの種類を表すコード
message 文字列 エラーメッセージ
出力されるメッセージの言語は、APIを実行したユーザーの表示言語の設定によって異なります。
表示言語の設定 (External link)
エラーの例
1
2
3
4
5
{
  "id": "1505999166-897850006",
  "code": "CB_IJ01",
  "message": "不正なJSON文字列です。"
}

日時のフォーマット

日時を扱うフィールドでは、次の形式の文字列を指定してください。

日付

フォーマット
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で出力されます。
一覧の設定を取得するAPI

日時(登録または更新するとき)

フォーマット
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の監査ログの確認方法/ログ一覧 (External link)
  • 1日に実行できるAPIは、1つのアプリにつき10,000件までです。
    リクエスト数にカウントされないAPIは、次のページを確認してください。
    1日に実行できるAPIリクエスト数 (External link)

制限事項

同時接続数

同時にリクエストできるAPIは、1ドメインにつき100までです。

レコードを操作するAPI

  • 複数のレコードを取得するAPIのoffsetで指定できるレコードの上限数は、10,000件までです。
    複数のレコードを取得するAPI
  • 一度に登録/更新/削除できるレコードは、100件までです。
  • 1つのテーブルに大量の行を追加しないでください。
    アプリの構成によっては負荷がかかり、レコードの表示やREST APIを使った操作などのレコードの処理に影響します。
    kintoneの性能を考慮したレコードの操作方法は、次のTipsを参照してください。
    kintoneの性能改善
  • 存在しないフィールドコードを指定して、レコードを取得/登録/更新した場合でも、存在しないフィールドコードは無視されて処理されます。
  • 次のフィールドは、値の取得のみです。登録や更新はできません。
  • レコードの登録や更新をするAPIでルックアップフィールドの値を変更する場合、ルックアップフィールドの「コピー元のフィールド」は、「レコード番号」フィールド、または「値の重複を禁止する」を設定したフィールドを指定してください。
  • ルックアップフィールドの「コピー元のフィールド」に、自動計算を設定している「文字列1行」フィールドを選択している場合、ルックアップフィールドの値は変更できません。

ファイルをアップロードするAPI

アップロードしたファイルは、一時保管領域に保存されます。
レコードの登録や更新をするAPIでレコードに添付しない限り、3日間で削除されます。
一時保管領域に保存したファイルは、ディスク使用量に含まれます。

レコードにコメントするAPI

一度に取得できるレコードのコメントは10件までです。

その他の制限事項