kintone REST API は、kintone のレコードやアプリ、スペースを操作できる API です。
kintone で管理しているデータを外部システムに渡すときや、外部システムから kintone へデータを登録、更新、削除するときに利用できます。

kintone REST API リクエスト を行う際、次の 4 つの情報が必要です。

URL

利用したい API のパスを指定します。どのリソースに対してリクエストを行うかを URL で指定します。
URL の一覧は、 REST API 一覧 を確認してください。

メソッド

URL で指定したリソースをどう扱うのか指定します。
GET／POST／PUT／DELETE のいずれかを指定します。

リクエストヘッダー

API を実行するリクエストには、認証のためのヘッダーを追加する必要があります。
kintone REST API のリクエストヘッダーに格納できる認証情報は、次の 2 種類があります。

• パスワード認証
  リクエストヘッダーに「X-Cybozu-Authorization」ヘッダーを追加し、値には「ログイン名：パスワード」を BASE64 エンコードしたものを指定します。
• API トークン認証
  アプリごとに生成する API トークンを使用して、kintone REST API を処理できます。
  リクエストヘッダーに「X-Cybozu-API-Token」ヘッダーを追加し、値にはアプリごとに生成する API トークンを指定します。
  API トークンを生成する方法は、 APIトークンを生成する を確認してください。

API トークンを使用すると、よりセキュアに REST API を実行できます。
アプリごとに生成するため、他のアプリに影響を与えることがありません。

リクエストヘッダーの仕様や制限を知りたい場合は kintone REST API の共通仕様 を確認してください。

リクエストパラメーター

Web API の記事で、REST API のリクエストパラメーターの役割について説明しました。
kintone REST API では、次の値をリクエストパラメーターに設定します。

• アプリ ID
• レコード ID
• record オブジェクト
  詳細は フィールド形式 を参照してください。
• スペースの本文に設定する文章など。

リクエストの内容によって、API に渡すパラメーターも異なるため、kintone REST API の各ドキュメントページに記載されている「パラメーター」を参考に、パラメーターを指定してください。

ここまでは kintone REST API の基礎知識について説明しました。
次の内容では実例を用いて kintone REST API の使い方を説明していきます。

kintone REST API を実行して、1 件のレコードデータを取得してみましょう。

まずは kintone REST API の実行において、必要な アプリ ID、レコード ID を確認する方法を紹介します。

アプリ ID やレコード ID を取得するには、次の 2 つの方法があります。

• kintone の API（ アプリの ID を取得する／ レコード ID を取得する）を使う。
• ブラウザーに表示されている kintone の URL から確認する。

今回は、ブラウザーに表示されている kintone の URL から確認してみましょう。

• アプリ ID
  ID を確認したいアプリの画面を開き、URL を確認してください。
  URL の「https://sample.cybozu.com/k/123」の末尾の数字部分は、アプリ ID です。
  上記の場合、アプリ ID は 123 になります。
• レコード ID
  ID を確認したいレコードの詳細画面を開き、URL を確認してください。
  URL の「https://sample.cybozu.com/k/123/show#record=456」の末尾の数字部分は、レコード ID です。
  上記の場合、レコード ID は 456 になります。

まずは REST API を手軽に試せる curl を使って、コマンドラインから kintone REST API を実行します。
1 件のレコードを取得する API で kintone アプリのレコードの内容を取得しましょう。

下準備として、kintone アプリを作成し、レコードを 1 件追加しておいてください。
ブラウザーの URL でアプリ ID とレコード ID を確認しておきます。

また、 APIトークンを生成する を参考にして、API トークンを発行しておきます。
今回はレコードを取得するので、「レコード閲覧」権限にチェックを入れます。

レコードを1件取得する にあるとおり、 レコードを取得するための URL は、「https://sample.cybozu.com/k/v1/record.json」、リクエストパラメーターは app と id です。

URL にリクエストパラメーターを含める方法で、app と id を指定してみましょう。
ベースとなる URL https://sample.cybozu.com/k/v1/record.json の後に ? をつけます。
リクエストパラメーターを「パラメーター名=値」の形式で記述し、リクエストパラメーターが複数ある場合は & で区切ります。
たとえば、アプリ ID が 11、レコード ID が 1 のレコードデータを取得する場合は、次のように書きます。

1
2

curl -X GET 'https://sample.cybozu.com/k/v1/record.json?app=11&id=1' \
  -H 'X-Cybozu-API-Token: API_TOKEN'

画面上に、作成したレコードの情報が表示されるはずです。

kintone 上で kintone REST API を利用する手段として、 kintone REST API リクエストを送信する API が用意されています。
kintone REST API リクエストを行う場合に利用する関数は次のとおりです。

kintone.api(pathOrUrl, method, params, successCallback, failureCallback)

pathOrUrl

REST API でデータを操作する際に、どのリソースに対してリクエストを行うかを URL で指定する必要があります。
kintone REST API リクエストを送信する際、引数の pathOrUrl 部分で URL を指定します。
たとえば、API の URL が「https://sample.cybozu.com/k/v1/xxx.json」の場合は、/k/v1/xxx.json を指定します。
ゲストスペース内アプリでも動作させる場合は、 URL を取得する API を使って kintone.api.url（"/k/v1/xxx.json", true）を指定します。

method

リソースに対して行う操作を指定する必要があります。
kintone REST API では、HTTP の一般的なリクエストメソッド GET（取得）、POST（作成）、PUT（更新）、DELETE（削除）を使って、操作を指定します。
たとえば、「レコードの取得（1 件）」のリクエストを行うときは、method 引数に GET を指定します。

params

リクエストを送信するときに、API へ渡したいパラメーターをオブジェクトで指定します。
リクエストの内容によって、API に渡すパラメーターも異なります。
kintone REST API の各ドキュメントページに記載されている「リクエストパラメーター」を参考に、オブジェクトを作成しましょう。

successCallback

successCallback は、API の呼び出しが成功したら実行されるコールバック関数です。
コールバック関数の引数には、API の実行結果を格納したオブジェクトが渡されます。
省略すると Promise を使って処理を行うことができます。
詳細は kintone カスタマイズで非同期処理をする で説明します。

failureCallback

failureCallback は、API の呼び出しが失敗したら実行されるコールバック関数です。
コールバック関数の引数には、API のエラー内容を格納したオブジェクトが渡されます。
successCallback と合わせて省略すると、Promise の catch メソッドでエラー内容を受け取ることができます。

サンプルコード

先ほど調べたレコード ID を RECORD_ID に指定して、レコード内容を取得するサンプルコードは次のとおりです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

(() => {
  'use strict';
  const RECORD_ID = '調べたレコードID';
  kintone.events.on('app.record.detail.show', (event) => {
    const url = kintone.api.url('/k/v1/record.json', true);

    // リクエストパラメータ
    const body = {
      app: kintone.app.getId(),
      id: RECORD_ID
    };

    kintone.api(
      url, // pathOrUrl
      'GET', // method
      body, // params
      (resp) => { // 成功時のコールバック関数
        console.log(resp);
      }
    );
  });
})();

リクエストが成功すると API の実行結果を格納したオブジェクトが引数（resp）に渡され、成功時のコールバック関数が実行されます。

基本的な kintone REST API の使い方を紹介しました。
しかし、「レコードを保存するときに別のアプリからレコードを取得して、その結果をフィールドにセットする」といった処理では Promise を利用してコードを書く必要があります。
次回は、 kintone カスタマイズで非同期処理をしてみよう を学習しましょう。

補足

kintone REST API には便利なライブラリがあります。
以下のライブラリを利用すると、用意されたメソッドを呼び出すだけで kintone REST API を実行でき、コードの記述量を減らすことができます。 kintone が提供している kintone REST API のほか、レコードを一括で処理できるメソッドなどの便利なメソッドも用意されています。

• @kintone/rest-api-client
• kintone Java Client

基本的な使い方を確認したい方は、次の説明記事を確認してください。

• kintone JavaScript Client
• kintone Java Client