はじめに
kintoneでカスタマイズをする際に、APIという言葉をよく耳にすると思います。特に「REST API」と「JavaScript API」という2つの主要なAPIがありますが、これらは目的や使い方が異なります。JavaScriptカスタマイズ初学者やREST APIを使い始めた人はこれらの概念がよくわからなくて躓くケースをよくみますので、簡単にまとめてみます。
kintone REST APIとは？
まず、REST APIについて説明します。REST APIは、サーバーとクライアント（例: ブラウザ）間でデータをやり取りするための標準的な仕組みです。kintoneのREST APIを使うと、アプリのデータ（レコード）を外部から操作できます。
kintone REST APIでできること
- レコードの作成、取得、更新、削除
- アプリの情報取得や、フィールドの操作
- 外部システムとのデータ連携
kintone REST APIの使い方の例
REST APIを使う際、通常はHTTPリクエスト（GET, POST, PUT, DELETEなど）を使用して、kintoneサーバーに対してデータを送受信します。以下は、JavaScriptカスタマイズでkintoneのREST APIを呼び出す例です。
（JavaScriptカスタマイズでは kintone.api() を使うことでREST APIを呼び出しやすくなっています。）
const body = {
"app": 123, // アプリID
"id": 456 // レコードID
};
kintone.api(kintone.api.url('/k/v1/record', true), 'GET', body, function(resp) {
console.log(resp); // レコードのデータを取得
});
kintone JavaScript APIとは？
一方、JavaScript APIは、kintoneアプリの中で、レコードの表示や編集といったイベントに基づいてその場で操作を行うための仕組みです。これは、ブラウザ内で動作し、ページのロード中に特定のイベントが発生した際に使います。
kintone JavaScript APIでできること
- レコードの表示や編集時にフィールドを自動で変更
- ボタンを押した時に特定の処理を実行
- フィールドの表示/非表示の切り替え
kintone JavaScript APIの使い方の例
JavaScript APIでは、特定のイベントに基づいて処理を実行します。例えば、レコードが表示された時にフィールドを非表示にする場合、以下のようなコードを使います。
kintone.events.on('app.record.detail.show', function(event) {
const field = kintone.app.record.getFieldElement('フィールドコード');
field.style.display = 'none'; // フィールドを非表示に
return event;
});
REST APIとJavaScript APIの違い
では、この2つのAPIはどう違うのでしょうか？以下に主な違いをまとめました。
| 特徴 | REST API | JavaScript API |
|---|---|---|
| 用途 | サーバーサイド・JavaScriptカスタマイズでのデータ操作 | クライアントサイド（ブラウザ内）での操作 |
| 使用場面 | 外部システムやアプリ間の連携、外部システムやアプリ間の連携、JavaScriptカスタマイズ内でのデータ取得・操作 | kintone内での動的な画面変更 |
| リクエスト方法 | HTTPリクエスト（GET, POSTなど）、JavaScriptカスタマイズの場合はkintone.api()の利用が可能。 |
イベント駆動型のJavaScript処理 |
| データ操作 | レコードのCRUD操作（作成・取得・更新・削除） | フィールドの表示変更や動作の制御 |
| 動作場所 | サーバーと通信してデータをやり取り | ユーザーのブラウザ内で実行 |
JavaScriptカスタマイズでREST APIを使う
kintoneのカスタマイズは主にJavaScript APIを使って行いますが、JavaScriptカスタマイズの中でもREST APIを利用することができます。たとえば、kintoneの画面上でレコードのデータをリアルタイムで更新したり、外部システムと連携してデータを取得する場合に、JavaScriptからREST APIを呼び出して処理を実行します。
kintone.events.on('app.record.detail.show', function(event) {
const body = {
"app": kintone.app.getId(),
"id": event.record.$id.value
};
kintone.api(kintone.api.url('/k/v1/record', true), 'GET', body, function(resp) {
console.log(resp); // レコードデータを取得して何か処理を行う
});
return event;
});
このように、JavaScript APIのイベント処理と組み合わせてREST APIを呼び出すことで、リアルタイムにデータを取得し、その場で画面に反映させたり、他のレコードを更新することができます。
ややこしいのは、JavaScript APIでも kintone.app.record.get() などレコードの情報を取得できるのになぜREST APIが必要なのか、というようなことがありますが、JavaScript APIで取れるデータは開いているレコード情報など制限があるため、自由にデータを取得したり登録したりする場合はREST APIを利用する必要があります。
どちらを使うべきか？
- 外部からkintoneのデータを操作したい場合：外部アプリやシステムからkintoneのデータを操作する場合は、REST APIを使います。たとえば、他のシステムからデータを自動的にkintoneに登録したり、kintoneのデータを他システムに同期する場合です。
- kintoneの画面上で動的な変更を行いたい場合：ページがロードされたときや、ユーザーがボタンを押した時に画面を動的に変えたい場合は、JavaScript APIを使います。フォームのフィールドを非表示にしたり、自動的に計算するフィールドを設定するなどの操作です。
- JavaScriptカスタマイズでREST APIを利用する場合：JavaScriptカスタマイズの中でも、他アプリのデータの取得や、レコードの詳細データを動的に取得・更新したい場合には、REST APIを呼び出して操作します。
まとめ
- REST APIは、外部からkintoneのデータを操作するために使います。サーバーと通信し、レコードの作成や取得、削除が可能です。
- JavaScript APIは、kintoneの画面上でリアルタイムに操作を行うための仕組みです。ブラウザ内で実行され、イベントに応じてUIを操作します。
- JavaScriptカスタマイズの中でREST APIを利用することも可能です。kintone上の操作にあわせてデータを操作するカスタマイズを行う際、REST APIを使うことで、データの取得や更新が可能になります。