kintone REST APIの共通仕様

更新日時
フォローする

Index

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

セッション認証

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

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

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

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

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

Basic認証

  • cybozu で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 エラーの種類を表すコードです。

注意事項

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

制限事項

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

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

アプリのレコード操作API

  • 一度に取得できるレコードは500件までです。
  • 一度に登録、更新、および削除できるレコードは100件までです。
  • 1つのテーブルに登録できる行数の上限値は5,000行までです。
  • レコード登録、更新において、存在しないフィールドコードを指定した場合は、そのフィールドコードへの処理は無視されます。
  • 1つのリクエスト内で存在するフィールドと存在しないフィールドが混在していた場合、存在しないフィールドは無視され、存在するフィールドは登録・更新が行われます。
  • レコード取得で存在しないフィールドコード名を指定した場合は、取得できません。
  • 次のフィールドは、レコードの取得 APIによって値の取得のみできます。レコードの登録API及びレコードの更新APIで値の登録と更新はできません。

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

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

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

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

その他の制限事項

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

関連Tips

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

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

Avatar
Shigeru SAWADA

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

Avatar
dylan

試用版を利用しているところ、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"}

Avatar
cybozu Development team

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

Avatar
cybozu Development team

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

Avatar
Shigeru SAWADA

cybozu.com developer network事務局さま

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

Avatar
miriorg

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

Avatar
Yutaro Hosoi

＞Moriatsu Iri

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

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

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