Web API

目次

API とは

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

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

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

Web API ≒ REST API

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

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

REST API の実行に必要なもの

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

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

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

URL

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

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

リソースの種類 URL
レコード(1件) /k/v1/record.json
レコード(複数) /k/v1/records.json
レコードコメント /k/v1/record/comment.json
スペース /k/v1/space.json

HTTP メソッド

どのようにしてリソースを操作するか」を表すのが 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 を実行する場合について説明します。

パラメーター名
id 1
row 10
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 を実行してみましょう。

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

curl

よく利用されている 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 で詳しく説明しています。

Postman

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

Postman API Platform | Sign Up for Free (External link)

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

XMLHttpRequest

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 メソッドでデータを送信

fetch

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

fetch API を利用すると、 Promise と async/await で学んだ 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 カスタマイズ でお会いしましょう!