はじめに
本記事はアイレット株式会社 22新卒 Advent Calendar 2022の3日目の記事です！
文系未経験で今年新卒で入社した私がWeb APIについて調べて要点を整理してみました。
調べる前は「何となくこういうもの」レベルの理解でしたが、ある程度自分の言葉で説明できるようになりました。
この記事を読むことで次のことが理解できます。
- Web APIとは何か
- Web APIの重要性
- いつどんな風に使われるのか
- エンドポイントの設計
Web API
Web APIの代表的な書籍であるWeb API: The Good Partsでは、API、Web APIをそれぞれ次のように定義しています。
-
API (Application Programming Interface)
「ソフトウェアコンポーネントの外部インターフェイス、つまりは機能はわかってるけれどもその中身の実際の動作は詳しくわからない（知らなくてもよい）機能のカタマリを、外部から呼び出すための仕様のこと」 -
Web API
「HTTPプロトコルを利用してネットワーク越しに呼び出すAPI」
つまり、プログラムからHTTPでURIにアクセスすることで便利な機能を利用できる仕組みがWeb APIになります。
Web APIにも定義はいくつかありますが、本記事ではURIにアクセスするとXML、JSON形式のデータが返ってくるものをWeb APIとして扱います。
Web APIの重要性
具体的なWeb APIの例を通して、なぜWeb APIが多くのウェブシステムで利用されているのかを見ていきます。
例1
総務省が提供している「e-Stat 政府統計の総合窓口」のAPIは、「国政調査」「人口推計」「退職公務員生活状況調査」等のデータを機械判読可能な形式(XML、JSON等)で提供します。
このAPIにアクセスすることで簡単に欲しいデータを入手して、自分のウェブシステムでデータを利用することができます。
APIを利用する企業が自前でデータをかき集める必要はなく、総務省が持つデータを簡単に活用することができます。
例2
Twilioが提供するAPIは、電話機能やSMS機能を提供します。
電話機能を提供するAPIを利用することで、通話できる機能を自前で構築、運用する必要がなくなります。
WebAPIを活用するメリット
Web APIを活用することで 自前でサービスを運用する必要がなくなり、時間やコストの削減に繋がります。
高度な知識を必要とするシステムでもWeb APIを利用すればシステムに組み込むことができます。
また、一般にWeb APIを公開する場合、APIを利用する企業や開発者から付加価値を与えられ、自社サービスの発展に繋がります。
Web APIはどのような場面で使われるのか
1.機能やデータの提供
先述したように、自分たちが作った機能やデータをWeb APIとして提供することでメリットを享受できます。
2.ウェブアプリケーション
Web APIは一般には公開せずに用いることも可能です。
かつてウェブアプリケーション開発において、新たな情報を取得する際にはページ遷移を伴わなければいけませんでした。
しかしながら、昨今のウェブアプリケーション開発では、AJAXと呼ばれる非同期通信の仕組みを利用することでページ遷移を伴わずに新たな情報を表示することが可能になりました。
これにより、やりとりするデータサイズを小さくしたり、データ操作を任意のタイミングでできるようになりました。
3.スマートフォン向けのアプリケーション
サーバーからのレスポンスを待たずに動作するスマホアプリ開発では、クライアントとサーバーのやりとりにWeb APIを使用します。
エンドポイントの設計
APIのエンドポイント＝URIです。
URIは利用する開発者にとって理解しやすいものでなければなりません。理解しづらいURIは、間違ったアクセスを招いてサーバーに負荷をかけたり、作り上げたAPIの評価を下げてしまいます。
公開するAPIでない場合でも、クライアントサイドとサーバーサイドで開発者が分かれることがあり、開発を円滑に進める上で分かりやすいエンドポイントを設計することが重要になります。
適切にURIを設計するためには次のようなことを意識する必要があります。
短く入力しやすいURI
次のURIにはホスト名とパスの両方に「api」という単語が含まれており重複しているため、パスの「api」を削ることで短くできます。
https://api.miura.com/api/search
短くシンプルなURIの方が、利用する側のスペルミスなどの間違いを減らすことができます。
人間が読んで理解できるURI
次のことを意識することで、より分かりやすいURIを設計することに繋がります。
- 省略形は極力使わない
- 英語を使う
- 一般的かつ適切な単語を使う
大文字小文字が混在していないURI
大文字、小文字のどちらを使うかは統一した方が良いです。その際、基本的には小文字が選択されます。
サーバ側のアーキテクチャが反映されていないURI
サーバー側の言語が何であるかといったサーバー側の情報をURIに反映させる必要はありません。利用者はサーバー側のアーキテクチャを知る必要がないためです。
ルールが統一されたURI
クエリパラメータ、パスパラメータを混在させることや、先述したように大文字小文字を混在させるといったことは、不恰好なだけでなく利用者を混乱させるため、ルールを統一する必要があります。
以下のURIは、複数形と単数系が混在、クエリパラメータとパスパラメータが両方使われている、といった問題があります。
https://api.miura.com/v1/users?id=1
https://api.miura.com/v1/user/5/message
クライアントを実装する際に誤解を招かないようにルールを統一する必要があります。
適切なHTTPメソッドを使う
URIは「操作されるもの(リソース)」HTTPメソッドは「何をするか」を表します。
1つのURIに目的に応じて異なるメソッドを使うことで、リソースとそれをどう扱うかを分離して適切に扱うことができます。
それぞれのメソッドは次のようにリソースに対する目的に応じて使い分けます。
| メソッド | 目的 |
|---|---|
| GET | 取得 |
| POST | 新規登録 |
| PUT | 更新 |
| DELETE | 削除 |
| PATCH | 一部変更 |
| HEAD | メタ情報の取得 |
GETメソッド
GETは指定したリソースを取得するために使われます。
リソースを変更する処理をGETメソッドに対して実装するべきではありません。
POSTメソッド
POSTメソッドは指定したURIに属する新しいリソースを新規登録するために使われます。
POSTの場合、次のようにデータの集合体を表すURIを指定します。
https://api.miura.com/v1/users
また、変更や削除用に別のメソッドが用意されているため、あくまでPOSTの使い道としては新規登録に留めておきましょう。
PUTメソッド
PUTは指定したリソースを変更するために使われます。
POSTとの違いとして、URIの指定の仕方が挙げられます。
PUTの場合は、変更対象の単体のデータを表すURIを指定する必要があります。
https://api.miura.com/v1/users/1
データの一部だけを変更したい場合はPATCHメソッドを使います。
DELETEメソッド
DELETEは指定したリソースを削除するために使われます。
複数形の名詞を利用する
基本的には「users」「products」のように複数形を用いるのが一般的です。
クエリパラメータとパスパラメータの使い分け
一意な特定のリソースを指定する場合は、パスパラメータを使うようにしましょう。例えば、ユーザーIDはパスで指定することが一般的なようです。
https://api.miura.com/v1/users/1
省略可能なパラメータの場合は、クエリパラメータを使うようにしましょう。例えば、ページネーションを実現するために「limit」を使う場合は、指定が無い時のデフォルト値を設定しておくことで省略できます。そのような場合はクエリパラメータを使うのが一般的です。
https://api.miura.com/v1/users?limit=50&offset=100
SSKDs向けのAPIにおけるエンドポイント
SSKDs向けのAPIとは、一般には公開せずAPIを利用する開発者が限られているAPIを指します。
このようなAPIの場合でも先述した設計ポイントは重要ですが、よりユーザー体験を考える必要があります。
例えば、1つの画面を構成するために多くの異なるAPIにアクセスするのは時間がかかってしまいます。
そのような場合、画面用の1つのAPIを用意してそのAPIに1度アクセスすることで画面を構成するのに必要な情報が全て得られるようにすることも1つの対策として考えられます。
おわりに
以上、Web APIについての説明・エンドポイントの設計の際に気をつけるポイントをまとめてみました。
ふわっと理解してた部分も含めて、改めて調べて整理する良い機会になりました。
明日は@SangaRyousukeくんの担当です！👍
参考文献
Web API: The Good Parts
Microsoft RESTful Web API の設計
e-Stat 政府統計の総合窓口