APIは「Application Programming Interface」の頭文字です。
と言っても、横文字が長くなっただけで、何が何だかわかりません。

あるサービスを利用するとき、普通は何らかの画面を操作したり、ボタンを押したりしますよね。
これらの画面やボタンは、サービスを「人間の手で操作する」ために作られたインターフェースです。

一方、APIは「Programming」の文字のとおり、サービスを「プログラムで操作する」ために作られたインターフェースです。
APIを利用すると、手で画面やボタンを操作せずとも、自分の開発したプログラムからサービスを操作できるのです。
開発者にとっては、とても便利なインターフェース。それがAPIです。

数あるAPIのうち、Web経由で使えるAPIを Web API と呼びます。
Web APIにはいくつか種類がありますが、近年では REST API と呼ばれるWeb APIが主流です。
ほとんどWeb API = REST APIといっても過言ではないくらいです。

REST APIはどういった設計思想を持ち、他のWeb APIと比べてどのような特徴があるのかについては、他の書籍などに説明をゆずるとして、ここでは「どうすればREST APIを使えるのか」についてお話します。

REST APIは、「操作したい対象（リソース）」と「行いたい操作」を送信することで、「操作した結果」を受け取ることができるAPIです。
たとえば、kintone REST APIでは、「レコード」と「取得する操作」を送信することで、「レコードの情報」を受け取ることができます。
「データの送信」をリクエストと呼び、「受け取った結果」をレスポンスと呼びます。
サービスに対し、URL、HTTPメソッド、リクエストヘッダー、リクエストパラメーターの4つをリクエストすることで、REST APIを実行できます。

• URL：リクエストの送信先となるURL
• HTTPメソッド：対象のリソースをどのように操作するか。
• リクエストヘッダー：リソースを操作するための認証情報や、送信するデータの種類など。
• リクエストパラメーター：リソースを操作するための具体的な内容

各項目について、詳しく説明します。

「どこにあるリソースへリクエストを送信するか」を表すのが URL です。REST APIではエンドポイントとも呼ばれます。
扱うリソースの種類ごとにURLが分かれており、URLを指定することで操作対象のリソースを選択できます。

次のURLは、kintone REST APIで利用できるリソースの種類とURLを抜粋したものです。

「どのようにしてリソースを操作するか」を表すのが HTTPメソッド です。
主にメソッドは4種類あり、どのようにリソースを操作するかで、メソッドを使い分けます。

• GET：リソースを取得する。
• POST：リソースを新規登録する。
• PUT：リソースを更新する。
• DELETE：リソースを削除する。

「事前にリクエスト先のシステムへ伝えておくべき情報」を含んでいるのが、リクエストヘッダーです。
認証情報や送信するデータの種類を表す情報をJSON形式で指定します。
サービスによって指定すべきリクエストヘッダーが異なりますので、実行するAPIの仕様を確認しましょう。

参考として、kintone REST APIを実行するときのリクエストヘッダーを例示します。

1
2
3
4

{
  "X-Cybozu-API-Token": "API_TOKEN", // kintoneのAPIトークン認証に必要なヘッダー情報
  "Content-Type": "application/json" // 送信するデータがJSON形式であることを表すヘッダー情報
}

「具体的なリソースの操作内容」を含んでいるのが、リクエストパラメーターです。
たとえば、データを表すIDや、サービスに登録したい文字列など、具体的なリクエストの内容を指定します。

リクエストパラメーターの指定方法は、2種類あります。
URLにパラメーターを含める方法と、リクエストボディにパラメーターを含める方法です。
「api.example.com」に対して、次のパラメーターでREST APIを実行する場合について説明します。

URLにパラメーターを含める方法

URLにパラメーターを含める方法は、とてもシンプルです。
URLの後に?をつけ、パラメーター名=値の形式で記述したリクエストパラメーターを、&でつなげていけばいいのです。

1

https://api.example.com?id=1&row=10

この方法は、一般的にGETやDELETEメソッドで使用します。

リクエストボディにパラメーターを含める場合

リクエストボディとは、リクエスト時に補足情報を表現できるスペースのようなものです。
リクエストヘッダーに事前情報を、リクエストボディに補足情報を記録できます。

リクエストボディにパラメーターを含める場合は、パラメーターをJSON形式で表現します。

1
2
3
4

{
  "id": 1,
  "row": 10
}

この方法は、一般的にPOSTやPUTメソッドで使用します。

REST APIの実行に必要なものがわかったので、実際にREST APIを実行してみましょう。

REST APIを実行できるクライアントは、さまざまなものがあります。 さまざまな種類のWebブラウザーが存在するのと同じですね。 ここでは、curl、Postman、XMLHttpRequest、fetch について説明します。

よく利用されているREST APIクライアントのひとつが、curl です。
curlはコマンドライン上からデータを送信できるプログラムで、REST APIのみならず、Webサイトを取得したり、ファイルをダウンロードしたりできます。
ここでは、主にREST APIを実行する方法に限って、curlの利用方法を説明します。

curlコマンドは、最新のWindowsやmacOSなら、インストール不要で利用できます。
試しに、GitHubが提供しているテスト用のWebサイトを、curlを使って取得してみましょう。

WindowsならPowerShellを、macOSならターミナルを起動して、次のコマンドを実行します。

1

curl https://api.github.com/zen

英語の文字がコマンドライン上に表示されれば、curlによるデータ通信に成功しています！ curlでREST APIを実行する場合は、次の形式で指定します。

1
2
3

curl -X HTTPメソッド "URL" \
  -H "リクエストヘッダー" \
  -d "リクエストボディ"

指定するURLやリクエストヘッダー、リクエストボディに設定するパラメーターは、APIを提供するサービスによって異なります。
curlを使ってREST APIを実行し、kintone上のデータを取得する方法は「はじめようkintone API」の REST APIで詳しく説明しています。

「コマンドラインはちょっと敷居が高い…」と感じた場合は、手軽にREST APIを実行できる Postman がおすすめです。

Postman API Platform | Sign Up for Free

Postmanは、URLやヘッダー、パラメーターなどをフォームに入力することで、ブラウザー上でREST APIを実行できるサービスです。
ただし、kintoneカスタマイズをするときは、これまでに学習したJavaScriptで書かれた「文字だけの」コードを読み解くことが必須です。
コマンドラインツールにもできるだけ慣れておくとよいでしょう。

XMLHttpRequest は、JavaScriptで利用できるデータ通信するためのAPIです。
次のようにコードを記述することで、JavaScript上でREST APIを実行できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// リクエストパラメータとして送信するオブジェクトを変数に代入
const body = {
  key: value
}

const xhr = new XMLHttpRequest(); // XMLHttpRequestオブジェクトを生成
xhr.open('HTTPメソッド', 'URL'); // openメソッドでHTTPメソッドとURLを指定
xhr.setRequestHeader('リクエストヘッダーのキー', 'リクエストヘッダーの値'); // setRequestHeaderメソッドでリクエストヘッダーを指定
xhr.onload = () => { // onloadメソッドで通信後の処理を指定
  if (xhr.status === 200) {
    // 通信に成功したときの処理
  } else {
    // 通信に失敗したときの処理
  }
};
xhr.send(JSON.stringify(body)); // sendメソッドでデータを送信

XMLHttpRequestの他にも、JavaScriptで利用可能なデータ通信のしくみは存在します。 そのうちのひとつが、fetch APIです。

fetch APIを利用すると、async/awaitを使って非同期処理をわかりやすく記述できます。
async/awaitの復習は、 Promiseとasync/awaitを確認してください。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

(async () => {
  try {
    // fetchメソッドの第一引数にURLを、第二引数にHTTPメソッドやリクエストヘッダー、リクエストボディを含むオブジェクトを指定
    const body = {}; // ボディに指定する値
    const response = await fetch('URL', {
      method: 'HTTPメソッド',
      headers: {
        リクエストヘッダーのキー: 'リクエストヘッダーの値'
      },
      body: JSON.stringify(body)
    });
    console.log(response.json());
  } catch (error) {
    console.log(error);
  }
})();

JavaScriptの学習、お疲れさまでした。
ここまで学習したあなたなら、kintoneカスタマイズも理解ができるはずです。

それでは、 はじめようkintoneカスタマイズでお会いしましょう！