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を実行する場合はセッション認証のみ利用できます。パスワード認証は利用できません。

OAuthクライアントを使用して認証することも出来ます。詳細はこちらを参照してください。

SAML認証設定時の利用について

SAML認証設定時に、パスワード認証、APIトークン認証でkintone REST APIを利用できます。
パスワード認証ではcybozu.comのログイン名とパスワードを利用する必要があります。
cybozu.com のログイン時に SAML 認証のみを使うように制限している場合、パスワード認証による kintone REST API の実行がcybozu.com共通管理者のみに制限されます。

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データをレスポンスとして受け取ります。

すべてのkintone REST APIのレスポンスヘッダには、次の情報が含まれています。

 X-ConcurrencyLimit-Limit:  100
 X-ConcurrencyLimit-Running:  2

kintone.api()でリクエストした場合のレスポンスについて

kintone.api()でkintone REST APIをリクエストした際、コールバックに渡される情報はレスポンスボディのみです。
そのため、レスポンスボディ以外の情報を利用する場合はkintone.api()以外でリクエストする必要があります。

注意事項

• リクエストデータ、およびレスポンスデータのJSONフォーマットには、今後フィールドやキーなどが追加される場合があります。
• アプリ、レコード、コメント、スペースなどの操作による監査ログは、「監査ログの一覧」 をご確認ください。
• 次のAPIはリクエスト数にカウントされません。
  
  • ファイルのダウンロード
  • ファイルのアップロード
  • スペース情報の取得
  • スペースの作成
  • スペースの本文の更新
  • スペースのスレッドの更新
  • スペースのスレッドへの投稿
  • スペースのメンバーの取得
  • スペースのメンバーの更新
  • ゲストスペースのゲストメンバーの更新
  • ゲストユーザーの一括追加
  • ゲストユーザーの一括削除
  • スペースの削除
  • API一覧の取得
  • API スキーマ情報の取得
• IPアドレス制限を行っている環境に対するREST APIリクエストについては、次のAPIリクエストがアクセス可能です。
  
  • アクセス許可されたIPアドレスがアクセス元となるAPIリクエスト
  • アクセス許可されたクライアント証明書を利用したAPIリクエスト

制限事項

ドメインへの同時接続

• APIによる同時接続数はドメインごとに100が上限です。

アプリのレコード操作API

• 一度に取得できるレコードは500件までです。
• 一度に登録、更新、および削除できるレコードは100件までです。
• 1つのテーブルに登録できる行数の上限値は5,000行までです。
• レコード取得、登録、更新において、存在しないフィールドコードを指定した場合は、そのフィールドコードへの処理は無視されます。
• 次のフィールドは、レコードの取得 APIによって値の取得のみできます。レコードの登録API及びレコードの更新APIで値の登録と更新はできません。
  • ルックアップフィールドによって値が入力されるフィールド
  • カテゴリー
  • 計算
  • ステータス (更新は、レコードのステータスの更新 API をご利用ください。)
  • 作業者（更新は、レコードの作業者の更新API をご利用ください。）
• レコード登録、更新において、ルックアップフィールドの値を変更する場合、ルックアップフィールドの「コピー元のフィールド」はレコード番号または「値の重複を禁止する」に設定されている必要があります。
• ルックアップフィールドの「コピー元のフィールド」に自動計算の設定をしている「文字列1行」フィールドを選択している場合、ルックアップフィールドの値は変更できません。

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

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

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

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

その他の制限事項

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

関連Tips

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