背景

WEB APIを美しく設計する方法を探しにきた。

読んだ本

O'Reillyの本を読んでみた
WEB API The Good Parts

章立て

前回のはこちら
WEB APIについて調べてみた -1章編-
今回は2章についてまとめてみた。
メモ程度の記述なので悪しからず。

API設計のルールや方法を知ろう

APIとして公開する機能を設計する

APIを公開するにはまず、何を掲載するのか決める必要がある。
非常にシンプルに考えるのであれば、例として仮にSNSサービスを提供するメンバーとなったつもりでAPI設計を考えると、以下のようなものが考えられると筆者は述べている。

番号	機能説明
1	ユーザーの登録や編集
2	友達の検索、追加、削除
3	友達の間でのメッセージのやりとり

こうした上記のようなAPIを公開すると考えることができたら、次にその公開APIがどのように使われるのか、ユースケースを考えるのが良い。

モバイルアプリケーション向けAPIに必要な機能

モバイルアプリケーションを例に、画面遷移を図にして書いてみることを勧めていた。
APIのリストと画面遷移の図、2つを見比べて過不足がないか考えると、個々の機能が最初に表で挙げたAPIだけで事足りるのかわかる。

APIエンドポイントの考え方

人間が理解できるURI

APIエンドポイントって何？

本文を引用すると以下になる。

Web APIにおけるエンドポイントとは、APIにアクセスするためのURIのこと
APIエンドポイントとは、URIのこと

良いURI設計って何？

重要な原則は
覚えやすく、どんな機能を持つURIなのかひと目でわかること。
また、筆者は一般的に重要な事柄を羅列していた。以下引用する。

・短く、入力しやすいURI
・人間が読んで理解できるURI
・大文字小文字が混在していないURI
・改造しやすいURI
・サーバ側のアーキテクチャが反映されていないURI
・ルールが統一されたURI

上記のような、大原則を意識しつつも、相手にとって理解しやすいURIを作るポイントが5つある。
それが、以下になる。

①むやみに省略形を使わない
一般的なURIがどのようになっているのか、それを知るためには他のURIを参考にするのが一番である。
②APIでよく使われている英単語を利用する
他のURIを参考にする場合は、1つではなく複数見ながら自分のURIを決めるのが望ましい。
③スペルミスをしない
複数形や過去形など間違いが生じがちなので、注意する必要あり。
④小文字のみで基本は書く
大文字小文字を混在させると、APIが分かりづらく間違えやすくなるリスクが生じる為。
⑤ルールを統一させる
ルールを統一させることで、開発者同士の情報連携がスムーズになる為。

HTTPメソッドとエンドポイント

APIとHTTPメソッドは関係性を持っており、その関係性を示したのが以下の図である。

URI（APIエンドポイント）へのアクセス方法として、HTTPメソッドと呼ばれる方法を利用する。
HTTPメソッドとは、HTTPでのアクセス時に指定するもので、メソッドには以下のように種類が存在する。

method_name	説明
GET	リソースの取得
POST	リソースの新規登録
PUT	既存リソースの更新
DELETE	リソースの削除
PATCH	リソースの一部変更
HEAD	リソースのメタ情報の取得

さて、ここで当初考えていたSNSサービスのAPIについてもう一度立ち返ることになる。
初めに挙げていたAPIの基本設計をメソッドも含めて考えると以下のようになる。

目的	エンドポイント	メソッド
ユーザー一覧取得	http://api.example.com/v1/users	GET
ユーザーの新規登録	http://api.example.com/v1/users	POST
特定のユーザーの情報の取得	http://api.example.com/v1/users/:id	GET
ユーザーの情報の更新	http://api.example.com/v1/users/:id	PUT/PATCH
ユーザーの情報の削除	http://api.example.com/v1/users/:id	DELETE

ここでいうIDは各ユーザーに割り当てられるものとし、v1とは、APIのバージョンを表す部分となっている。
API自体は5つになっているが、エンドポイントは2つに絞って設計されている。

検索とクエリパラメータの設計

エンドポイントの設計が出来たところで、次に検索について考えていく。
作成されたエンドポイントにより、ユーザー一覧が取得出来るようになったとしよう。
仮に、登録者数1万人を超えるユーザーが利用するSNSサービスだった場合、その中から絞り込み検索を使って誰かを特定したい場合も出てくる。そうした時、利用するのがクエリパラメータと呼ばれるものである。

クエリパラメータって何？

URLの後ろに?を付け足し、その後ろに付け加えるパラメータのこと。と本文には記載されている。
これだけではよくわからなかったのが正直なので、ググった。
詳細はURLクエリパラメータ(クエリストリング)の意味とは。を参照してほしい。

絞り込み検索を仕込むにはどうする？

まず、たくさんあるデータの一部を取得する際に、どういsったパラメータで取得数と取得位置を指定するのかを考える必要がある。
この考えは**ページネーション(pagination)**と呼ばれるらしい。
クエリパラメータの例として以下の表が記入されていた。

サービス名	取得数	取得位置(相対位置)	取得位置(絶対位置)
Twitter	count	cursor	max_id
Youtube	maxResults	pageToken	publishedBefore/publishedAfter
Flickr	per_page	page	max_upload_date
Instagram	-	-	max_id

相対位置と絶対位置

相対位置と絶対位置を理解するには、そもそも相対パスと絶対パスの概念も知る必要がある。
詳細は絶対パスと相対パスについてを参照すると良いだろう
この節で言いたかったのは結局相対位置で指定するのではなく、絶対位置で指定した方がよいということを結論付けていたのだが、相対位置であるとダメな理由として以下のような内容が記載されていた。（要約）

問題は大きく2つある。
1つは、データ量増量による相対位置把握の困難さである。
データ件数が少なければ問題ないが、サービスを続けていくうちに増加するデータと共にパフォーマンスが低下し、問題が発覚する場合もある為。
もう1つは、更新頻度の高いデータに不整合が生じる為。
例えば最初の20件を取得してから次の20件を取得する間に更新が入ってしまった場合、ズレが生じてしまうから。

上記のような理由で、相対位置による定義は避けた方が良い。

クエリパラメータとパスの使い分け

クエリパラメータに入れる情報は、URI中のパス部分に入れることも設計としては可能である。
URIに入れるかどうかを決めるには、以下項目を意識すると良いとされる。

・一意なリソースを表すのに必要な情報かどうか
　URI自体、リソースを表すものという大前提の元成り立っているので、ユーザーIDを入れたりすることで一意に決まる。
・省略可能かどうか
　省略可能であれば、クエリパラメータの方が適している。

ログインとOAuth 2.0

SNSのAPIを設計するにあたり、まだ扱っていないAPIがあった。ここではログイン、つまり認証のAPIについて扱う。
ログイン周りのAPIを考える時に真っ先に検討すべきはOAuthと呼ばれる標準的な仕様だ。
OAuthは基本的に第三者に公開されるAPIにおいて認可を行う為に用いられる。
詳細は一番分かりやすい OAuth の説明を参照してほしい。

まとめ

著書内でまとめてあったものをそのまま引用する。

・覚えやすく、どんな機能を持つかひと目でわかるエンドポイントにする
・適切なHTTPメソッドを利用する
・適切な英単語を利用し、単数形、複数形にも注意する
・認証にはOAuth２．０を使う

感想

章自体は読みやすい。ただ後半になるにつれて概念的に分かってない場合はまあまあ辛い。
OAuthについてがまだまだ深掘り出来ていないし、アクセストークンの流れも追えてないので再復習しよう。。