kintone REST APIの共通仕様

kintone REST APIの概要

kintone アプリのレコードの操作やフォーム設計情報の取得、スペースを操作することができます。

プロトコル

HTTPS

フォーマット

JSON

文字コード

UTF-8

エスケープ文字

「\」を使用します。

日時のフォーマット

日付、時刻、日時フィールド（作成日時、更新日時フィールドも含む）のデータを扱う場合、それぞれ以下のフォーマットの文字列で指定する必要があります。

ユーザー認証

APIを実行するリクエストには、認証のためのヘッダを追加する必要があります。

パスワード認証

// ログイン名が「Administrator」、パスワードが「cybozu」の場合
X-Cybozu-Authorization:QWRtaW5pc3RyYXRvcjpjeWJvenU=

APIトークン認証

アプリごとに生成するAPIトークンを使用して、kintone REST APIを処理できます。 APIトークンを生成する方法は、こちら をご確認ください。

// APIトークンが「BuBNIwbRRaUvr33nWXcfUZ5VhaFsJxN0xH4NPN92」の場合
X-Cybozu-API-Token:BuBNIwbRRaUvr33nWXcfUZ5VhaFsJxN0xH4NPN92

• 組織間のアクセス権の設定を有効にすると、APIトークンを生成/閲覧できるのはkintoneシステム管理者のみになります。

セッション認証

セッション認証とは、Webサーバから付与されたセッションIDをCookieに保存する事でユーザを識別する認証方法です。

認証時の優先順位について

優先順位は以下の通りです。

1. パスワード認証
2. APIトークン認証
3. セッション認証

ゲストユーザがAPIを実行する場合はセッション認証のみ利用できます。パスワード認証は利用できません。

Basic認証

// ログイン名が「Administrator」、パスワードが「cybozu」の場合
Authorization:Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=

リクエストヘッダ

送信するリクエストに応じて以下のリクエストヘッダを指定します。

POST /k/v1/records.json
Host: example.cybozu.com:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Content-Type: application/json
X-HTTP-Method-Override: GET

{
    "app":"8",
    "query":"更新日時 > \"2012-02-03T09:00:00Z\" and 更新日時 < \"2012-02-03T10:00:00Z\""
}

リクエストURI

https://(サブドメイン名).cybozu.com/k/v1/(コマンド名).json

ゲストスペース内のアプリの場合

https://(サブドメイン名).cybozu.com/k/guest/(スペースのID)/v1/(コマンド名).json

• 「コマンド名」は、APIの種類ごとに異なります。
• 「v1」は固定値です。

レスポンス

HTTPステータスコードが「200」であれば正常終了、それ以外はエラー終了です。 エラー時には下記情報を含むJSONデータをレスポンスとして受け取ります。

注意事項

• リクエストデータ、およびレスポンスデータのJSONフォーマットには、今後フィールドやキーなどが追加される場合があります。
• アプリ、レコード、コメント、スペースなどの操作による監査ログは、「監査ログの一覧」 をご確認ください。
• 次のAPIはリクエスト数にカウントされません。
  
  • ファイルのダウンロード
  • ファイルのアップロード
  • スペース情報の取得
  • スペースの作成
  • スペースの本文の更新
  • スペースのスレッドの更新
  • スペースのスレッドへの投稿 ※2016/8/14の定期メンテナンス後に利用できる機能です。
  • スペースのメンバーの取得
  • スペースのメンバーの更新
  • ゲストスペースのゲストメンバーの更新
  • ゲストユーザーの一括追加
  • ゲストユーザーの一括削除
  • スペースの削除
  • API一覧の取得
  • API スキーマ情報の取得

制限事項

ドメインへの同時アクセス

• APIによる同時アクセス数はドメインごとに10が上限です。

アプリのレコード操作API

• 一度に取得できるレコードは500件までです。
• 一度に登録、更新、および削除できるレコードは100件までです。
• 1つのテーブルに登録できる行数の上限値は5,000行までです。
• レコード登録、更新において、存在しないフィールドコードを指定した場合は、そのフィールドコードへの処理は無視されます。
• 1つのリクエスト内で存在するフィールドと存在しないフィールドが混在していた場合、存在しないフィールドは無視され、存在するフィールドは登録・更新が行われます。
• レコード取得で存在しないフィールドコード名を指定した場合は、取得できません。
• 次のフィールドは、レコードの取得 APIによって値の取得のみできます。レコードの登録API及びレコードの更新APIで値の登録と更新はできません。
  • ルックアップフィールドによって値が入力されるフィールド
  • カテゴリー
  • 計算
  • ステータス (更新は、レコードのステータスの更新 API をご利用ください。)
  • 作業者（更新は、レコードの作業者の更新API をご利用ください。）

ファイルのアップロードAPI

• アップロードされたファイルは、レコード登録 API やレコード更新 API によってレコードに添付しない場合には、3日間で削除されます。 保管されたファイルも、ディスク使用量に含まれます。

アプリのレコードコメントAPI

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

その他の制限事項

• その他、サービスに関する制限事項は、こちら をご確認ください。

関連Tips

• APIトークンを使ってみよう
• CSRFトークン利用時の注意点