カテゴリー内の他の記事

kintone REST APIの共通仕様

作成日2014年05月08日 07:21
更新日2018年11月06日 02:50

Index

kintone REST APIの概要
ユーザー認証
Basic認証
リクエストヘッダ
レスポンス
注意事項
制限事項
関連Tips

kintone REST APIの概要

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

プロトコル

HTTPS

フォーマット

JSON

文字コード

UTF-8

エスケープ文字

「\」を使用します。

日時のフォーマット

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

フィールドタイプ	フォーマット	説明
日付	YYYY-MM-DD	UTCに変換されません。以下のような形式の入力を受け付けます。　* 2015 　* 2015-07 　* 2015-7 　* 2015-7-5 月日を省略した場合は01で補完されます。　* 2015 -> 2015-01-01 　* 2015-07 -> 2015-07-01 　* 2015-7 -> 2015-07-01 　* 2015-7-5 -> 2015-07-05
時刻	HH:MM:SS	UTCに変換されません。
日時	取得時 YYYY-MM-DDTHH:MM:SSZ	「YYYY-MM-DD」と「HH:MM:SS」の間の「T」は固定値です。「HH:MM:SS」の後ろの「Z」は固定値です。取得時の「Z」はUTCを表します。一覧の取得APIでは日時はUTCで出力されます。日本時間（JST）の2012年3月22日14時00分は次のように表せます。例）「2012-03-22T05:00:00Z」「T」以降を省略した場合、UTCとして扱われます。
日時	登録・更新時 YYYY-MM-DDTHH:MM:SS±HH:MM または YYYY-MM-DDTHH:MM:SSZ	「YYYY-MM-DD」と「HH:MM:SS」の間の「T」は固定値です。「HH:MM:SS」の後ろの「Z」は固定値です。登録・更新時の「±HH:MM」には、UTCとの時刻の差を指定します。日本時間（JST）の2012年3月22日14時17分は次のように表せます。例1）「2012-03-22T14:17:00+09:00」例2）「2012-03-22T05:17:00Z」「T」以降を省略した場合、UTCとして扱われます。

ユーザー認証

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

パスワード認証

リクエストヘッダに「X-Cybozu-Authorization」を追加し、「ログイン名:パスワード」をBASE64エンコードしたものを値に指定します。

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

APIトークン認証

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

リクエストヘッダに「X-Cybozu-API-Token」を追加し、アプリごとに生成するAPIトークンを値に指定します。
生成できるトークンは、アプリ1つにつき20個までです。
APIトークンを使用した操作は、Administratorによる操作として記録されます。
リクエストヘッダに「X-Cybozu-Authorization」を指定していると、その認証が優先されます。
APIトークンは、アプリを操作する次のkintone REST APIで使用できます。
- レコードの操作（登録／更新／取得／削除）
  ※ルックアップフィールドの値を登録／更新できません。
- フォーム設計情報の取得
- ファイルのアップロード/ファイルのダウンロード
- アプリの取得
- ステータスの更新
- ステータスの一括更新
セキュアアクセスを設定している場合、APIトークンでの認証はエラーになります。

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

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

セッション認証

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

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

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

パスワード認証
APIトークン認証
セッション認証

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

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

Basic認証

cybozu.com でBasic認証を利用している場合は、更にリクエストヘッダに「Authorization」ヘッダを追加し、「Basic 」と「ログイン名:パスワード」をBASE64エンコードしたものを値に指定します。
- 「Basic」と「ログイン名:パスワード」の間は、半角空白が必要です。
- 「Basic 」の BASE64エンコードは不要です。
ゲストスペース内のアプリは対象外です。

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

リクエストヘッダ

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

ヘッダー名

内容

Host

サブドメイン名.cybozu.com:443

Content-Type

application/json

※リクエストボディにJSON文字列を格納する場合のみ指定します。

X-HTTP-Method-Override

HTTPメソッド(GET, POST, PUT, DELETE)

X-HTTP-Method-OverrideにHTTPメソッドを指定してPOSTリクエストを送信すると、指定したHTTPメソッドに対応するAPIが実行されます。

X-HTTP-Method-OverrideヘッダはPOSTリクエストの時のみ有効になります。
X-HTTP-Method-Overrideを使ったAPI呼び出しは全てのkintone REST APIで利用できます。
X-HTTP-Method-Overrideに指定するHTTPメソッド名は大文字のみ使用可能です。

※リクエストURIが8KBを超えると発生するエラー(Request URI Too Large)を回避する目的で使用します。
※kintone.api()でURIの長さが4KBを超えるGETリクエストが送信された場合、X-HTTP-Method-Overrideヘッダが自動的に付与され、
　POSTリクエストとして送信されます。
※kintone.proxy()については動作保証外となります。

以下のリクエストを送信した場合、レコード一括取得APIが実行されます。

リクエストヘッダ

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

Key	Value
message	エラーメッセージが表示されます。ユーザーの言語によって異なります。
id	エラーIDです。問い合わせの際に利用します。
code	エラーの種類を表すコードです。

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

Key

Value

X-ConcurrencyLimit-Limit

同時接続数の上限値

固定値の100です。

X-ConcurrencyLimit-Running

現在の同時接続数

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

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

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

注意事項

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

制限事項

ドメインへの同時接続

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

アプリのレコード操作API

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

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

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

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

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

その他の制限事項

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

記事に関するフィードバック

直接的に記事と関連がないご質問はcybozu developer コミュニティをご活用ください。

Shigeru SAWADA 2016年02月26日 05:37

REST APIエラー時のレスポンスのcode(エラーコードの種類)について、公開はないのでしょうか？
一般的なものだけでも公開していただけるとありがたいのですが。
具体的には、同時アクセスによるエラーコードが"GAIA_RE18"で返って来ているようなので、
この場合個別にハンドリングしてリトライさせたいのですが、
公式で公開していただけると安心してハンドリングロジックを入れられるので。

dylan 2016年04月01日 09:32

試用版を利用しているところ、REST　APIの呼び出しが失敗しました。
試用版でREST APIの利用が可能でしょうか。
curl -H "X-Cybozu-API-Token: (作成したAPIトークン)" "https://(サブドメイン名).cybozu.com/k/v1/record.json?app=9&id=1"
で試しましたが、、認証が通らないようです。

HTTP 520のレスポンスメッセージ
{"message":"ログインしてください。","id":"1505999166-787662019","code":"CB_AU01"}

cybozu development team 2016年04月12日 00:25

Shigeru SAWADAさん
cybozu.com developer network事務局です。
残念ながら今のところ公開予定はありません。
ただ、要望は多い所ではあるので将来的に検討していきたいと思います。

cybozu development team 2016年04月12日 00:25

Shigeru SAWADA
cybozu.com developer network事務局です。
恐らくなにかパラメータが間違っているはずです…認証キーの設定等を見返してみてください。

Shigeru SAWADA 2016年04月18日 07:30

cybozu.com developer network事務局さま

回答ありがとうございました。
是非とも将来的に検討のほどよろしくお願いします。

miriorg 2016年08月04日 09:22

アプリの一覧を取得するAPIは存在しないのでしょうか?

Yutaro Hosoi 2016年08月22日 02:23

＞Moriatsu Iri

アプリ情報取得APIの一括取得をすればよいかと。

https://cybozudev.zendesk.com/hc/ja/articles/202931674

flowers 2017年11月24日 05:59

API連携を検討しております。上限5,000行を超える場合の方法は何かありませんでしょうか。

cybozu Development team 2017年11月27日 07:34

iwasaki様

>1つのテーブルに登録できる行数の上限値は5,000行までです

についてのご相談でしょうか。

仕様外についてのご質問は、具体的に希望される動作を明記の上cybozu developer コミュニティに投稿ください。

suzuki 2018年04月18日 07:58

APIリクエスト数10,000件の制限があると思いますが、

それに関連して現在のAPIリクエスト数を取得するAPIはございますでしょうか。

cybozu Development team 2018年04月19日 06:58

suzuki 様

お世話になっております。developer network 運営チームです。

現在のAPIリクエスト数を取得するAPIはございません。
ご希望に添えず申し訳ございません。

なお、現在のAPIリクエスト数はアプリ管理画面にてご確認いただけます。
詳しくはこちらをご確認ください。

今後ともよろしくお願いいたします。

Yasuyuki Tanaka 2018年04月21日 15:22

プロセス管理に関するREST APIのページへのリンクが左部ツリーメニューより消えています。

APIの廃止や使用の非推奨が予定されているのでしょうか？

Yasuyuki Tanakaにより編集されました 2018年04月21日 15:23

cybozu Development team 2018年04月23日 00:26

田中　靖之様

お世話になっております。developer network 運営チームです。

大変申し訳ございません、メニュー表示に誤りがあったため修正いたしました。
プロセス管理のAPIにについて、廃止予定はございません。

ご指摘いただきましてありがとうございました。
今後ともよろしくお願いいたします。

Yasuyuki Tanaka 2018年04月23日 06:31

developer network 運営チーム様

ご回答ありがとうございました。

APIに変更がないとのことで安心しました。

今後ともよろしくお願いいたします。

ログインしてコメントを残してください。

Index

kintone REST APIの概要

プロトコル

フォーマット

文字コード

エスケープ文字

日時のフォーマット

ユーザー認証

パスワード認証

APIトークン認証

セッション認証

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

Basic認証

リクエストヘッダ

リクエストURI

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

レスポンス

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

注意事項

制限事項

関連Tips

記事に関するフィードバック