WEB APIのエンドポイント設計

こんにちは、SESエンジニアのつくねん。です。
前回に引き続きWEB APIのお話です（参考は「Web API The Good Parts」）
今回はエンドポイント設計について

エンドポイント設計って？

WEB APIでのエンドポイントとはURIのこと。
つまり、APIの機能を使うためのURIを決めようってことです。
設計の際に何に気をつけるべきか
「Web API The Good Parts」の筆者は以下のようにまとめています。

どんなURIにすれば良いのか？

実際にエンドポイント（URI）を設計するうえで以下のようにすることで
覚えやすく、どんな機能を持つURIなのかひと目でわかる設計になるとのことです。６つポイントがあります！！

①短く入力しやすいURI
必要最低限の情報で構成する。（無駄な情報を持たせない）

②人間が読んで理解できるURI
・単語の省略形を使わないこと（国際規格で標準化されているもの、例えば jp などはOK）
・APIでよく使われる英単語を使うこと（既存の他APIを参考にすると良し）
・英語のスペルミスや誤用をしないこと（英語っぽいけど英語にならない言葉や和製英語は避けましょう）

③大文字小文字が混在していないURI
・混在しているとわかりにくいので小文字で統一すると良い（ホスト名が通常小文字なので合わせて）
・文字を繋げて表現しているもの（getUserNameみたいな）ものはあまりよろしくない

④改造しやすいURI
・URIを修正して他のURIにしやすいようにする
・ドキュメントを見なくてもある程度想像できるくらいにする
　例えば以下のURIでは1234の部分がitemのIDだと推測できる
　そして、その部分を変更するだけで、他のitem取得が可能だと予測できる

http://api.example.com/v1/item/1234

⑤サーバ側のアーキテクチャが反映されていないURI
・サーバー側のアーキテクチャ（どんなサーバーで、どんな言語で、どんなディレクトリシステムかなど）をわかるようにしない
以下のようなものはNG（PHP で書かれていてCGIとして動作するのがバレバレ）

http://api.example.com/cgi-bin/get_user.php?user=100

⑥ルールが統一されたURI
・利用する単語、URIの構造を統一する
以下の２つのURIは異なるルールで構築された例です。

1.友達の情報の取得
http://api.example.com/friends?id=100

2.メッセージの投稿
http://api.example.com/friend/100/message

1.はfriendsと複数形＋クエリパラメータでidを指定
2.はfriendやmessageが単数系＋idはURIのパスに入れている
このようなことはトラブルの温床になると想像されるので避けるべき。

おわりに

以上がWEB APIエンドポイント設計のポイント6つです！
上記を学んだ後は、他のAPIのエンドポイントがどうなっているのか、気になるようになりました。実際に自分で設計するようになった際には上記を念頭に置いて進めたいものです。。。