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の後に?をつけます。
リクエストパラメーターを「パラメーター名=値」の形式で記述し、リクエストパラメーターが複数ある場合は&で区切ります。 そのため、?app=アプリID&id=レコードIDという形式でリクエストパラメーターを指定します。

1
2
3

# アプリIDが11でレコードIDが1の場合
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