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 では、「レコード」と「取得する操作」を送信することで、「レコードの情報」を受け取ることができます。
「データの送信」をリクエストと呼び、「受け取った結果」をレスポンスと呼びます。
サービスに対し、URL、HTTP メソッド、リクエストヘッダー、リクエストパラメーターの 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 を実行するときのリクエストヘッダーを例示します。
|
|
リクエストパラメーター
「具体的なリソースの操作内容」を含んでいるのが、リクエストパラメーターです。
たとえば、データを表す ID や、サービスに登録したい文字列など、具体的なリクエストの内容を指定します。
リクエストパラメーターの指定方法は、2 種類あります。
URL にパラメーターを含める方法と、リクエストボディにパラメーターを含める方法です。
「api.example.com」に対して、次のパラメーターで REST API を実行する場合について説明します。
パラメーター名 | 値 |
---|---|
id | 1 |
row | 10 |
URL にパラメーターを含める方法
URL にパラメーターを含める方法は、とてもシンプルです。
URL の後に ?
をつけ、パラメーター名=値
の形式で記述したリクエストパラメーターを、&
でつなげていけばいいのです。
|
|
この方法は、一般的に GET や DELETE メソッドで使用します。
リクエストボディにパラメーターを含める場合
リクエストボディとは、リクエスト時に補足情報を表現できるスペースのようなものです。
リクエストヘッダーに事前情報を、リクエストボディに補足情報を記録できます。
リクエストボディにパラメーターを含める場合は、パラメーターを JSON 形式で表現します。
|
|
この方法は、一般的に POST や PUT メソッドで使用します。
REST API を実行する
REST API の実行に必要なものがわかったので、実際に REST API を実行してみましょう。
REST API を実行できるクライアントは、さまざまなものがあります。 さまざまな種類の Web ブラウザーが存在するのと同じですね。 ここでは、curl、Postman、XMLHttpRequest、fetch について説明します。
curl
よく利用されている REST API クライアントのひとつが、curl です。
curl はコマンドライン上からデータを送信できるプログラムで、REST API のみならず、Web サイトを取得したり、ファイルをダウンロードしたりできます。
ここでは、主に REST API を実行する方法に限って、curl の利用方法を説明します。
curl コマンドは、最新の Windows や macOS なら、インストール不要で利用できます。
試しに、GitHub が提供しているテスト用の Web サイトを、curl を使って取得してみましょう。
Windows なら PowerShell を、macOS ならターミナルを起動して、次のコマンドを実行します。
|
|
英語の文字がコマンドライン上に表示されれば、curl によるデータ通信に成功しています! curl で REST API を実行する場合は、次の形式で指定します。
|
|
指定する URL やリクエストヘッダー、リクエストボディに設定するパラメーターは、API を提供するサービスによって異なります。
curl を使って REST API を実行し、kintone 上のデータを取得する方法は「はじめよう kintone API」の
REST API で詳しく説明しています。
Postman
「コマンドラインはちょっと敷居が高い…」と感じた場合は、手軽に REST API を実行できる Postman がおすすめです。
Postman API Platform | Sign Up for Free
Postman は、URL やヘッダー、パラメーターなどをフォームに入力することで、ブラウザー上で REST API を実行できるサービスです。
ただし、kintone カスタマイズをするときは、これまでに学習した JavaScript で書かれた「文字だけの」コードを読み解くことが必須です。
コマンドラインツールにもできるだけ慣れておくとよいでしょう。
XMLHttpRequest
XMLHttpRequest は、JavaScript で利用できるデータ通信するための API です。
次のようにコードを記述することで、JavaScript 上で REST API を実行できます。
|
|
fetch
XMLHttpRequest の他にも、JavaScript で利用可能なデータ通信のしくみは存在します。 そのうちのひとつが、fetch API です。
fetch API を利用すると、 Promise と async/await で学んだ async/await で非同期処理をわかりやすく記述できます。
|
|
おわりに
JavaScript の学習、お疲れさまでした。
ここまで学習したあなたなら、kintone カスタマイズも理解ができるはずです。
それでは、 はじめよう kintone カスタマイズ でお会いしましょう!