WebAPI The Good Partsを読んで Part1 エンドポイントの設計編
こちらはLancers（ランサーズ）Advent Calendar 2020の17日目の記事です。(遅くなりすみません；；)
WebAPI The Good Partsを読んだので1~2章に書かれていたことをまとめました。
まず用語の解説
WebAPI
API(Application Programming Interface)とは
機能はわかってるけれどもその中身の実際の動作は詳しくわからない（知らなくてもよい）機能のカタマリを、外部から呼び出すための仕様のこと。
HTMLは最終的に人間がブラウザ上で読むことを前提として情報が埋め込まれている一方、APIはデータを直接活用するための形式。
URI
URIとはURLとURNの総称のこと。
| 略称 | 名称 | 意味 |
|---|---|---|
| URI | Uniform Resource Identifier | URLとURNの総称 |
| URL | Uniform Resource Locator | 1つのファイルの「住所」を示す |
| URN | Uniform Resource Name | 1つのファイルの「名前」を示す |
エンドポイント
APIにアクセスするためのURIのこと。
設計を美しくする重要性について
設計の美しいWebAPIは使いやすい
クライアントとサーバーサイドで開発者が異なる場合、設計が美しいと意思疎通を図る上で齟齬が出にくく、ドキュメントを見る頻度が減る。そのため、美しい設計が開発期間や開発者のストレス軽減に大きく影響する。
設計の美しいWebAPIは変更しやすい
いきなりAPIの仕様が変わると、API利用者のシステムやサービスがいきなり動かなくなってしまうため、変更しやすいAPIである必要がある。なお、モバイルアプリケーションの場合、アプリケーションのアップデートはユーザー次第なので急に変化させると古いバージョンが動かなくなる。
設計の美しいWebAPIは頑強である
APIは誰でもアクセス可能なため、HTTPを利用してる以上セキュリティの問題を考慮する必要がある。そのためセキュリティを考慮したAPIは美しいと言える
設計の美しいWebAPIは恥ずかしくない
開発者目線で美しくない、センスの疑われるAPIを公開すると開発者の技術レベルが疑われる。そのため良い開発者が集められない可能性がある。
エンドポイントの設計で重要なこと
「覚えやすく、どんな機能を持つURIなのかが一目でわかる」というのが良いエンドポイントの設計です。そのために意識する点が以下です。
短く入力しやすいURI
✖︎ 重複していたり、類似な言葉を含む
http://api.example.com/service/api/search
◯ 短くてシンプル
http://api.example.com/search
→ 理解しやすく、覚えやすく、入力間違いも少ない
人間が読んで理解できるURI
✖︎ 意味不明な省略形が使われている
http://api.example.com/sv/u/
◯ APIでよく使われている英単語を利用する ※スペルミスをしない。
→ 毎回ドキュメントを参照しなくてよくなる
本書の中では下記サイトがよく使われている英単語を調べる上で良いとのこと
大文字小文字が混在していないURI
混在はAPIをわかりづらく、間違えやすくするので、基本的には小文字で統一する。
既存のAPIにおいては、大文字が混じると404 NotFoundを返すものも多い(GitHub、Tumblrなど)
なおHTTPにおいて、URIは「スキーマとホスト名を除いては大文字と小文字は区別される」と仕様に書かれている(RFC7230)
改造しやすい(Hackableな)URI
HackableとはURIを修正して別のURIにするのが容易であること。
http://api.example.com/v1/items/123456
上記のURIは直感的にアイテムIDが123456であることがわかり、別のIDに変えれば別のアイテムにアクセスできることがわかる。
あるURIから他のURIを想像することができれば、あまりドキュメントを見なくても開発を進めることができる。またドキュメントを見なかったことによって引き起こされるバグなどの問題も起こりづらくなる。
サーバ側のアーキテクチャが反映されていないURI
どんなサーバソフトウェアを利用しているか、どんな言語を使って実装を行っているか、サーバサイドのディレクトリやシステム構成がどうなっているのか等の情報はAPI利用者側には必要なく、攻撃を受ける可能性をあげてしまう
✖️http://api.example.com/cgi-bin/get_user.php?user=100
→PHPで書かれていてCGIとして動作していることがわかってしまう
URIが反映すべきはサーバ側のアーキテクチャではなく、機能やデータの構造。
ルールが統一されたURI
･友達の情報の取得 http://api.example.com/friends?id＝100
･メッセージの投稿 http://api.example.com/friend/100/message
上記2つのURIは、単数形と複数形が混在している上に、IDの取得もクエリパラメータとパスが混在している。クライアントを実装する際に混乱するほか、トラブルの温床になるので統一する。
HTTPメソッド
| メソッド名 | 説明 |
|---|---|
| GET | リソースの取得 |
| POST | リソースの新規登録 |
| PUT | 既存リソースの更新 |
| DELETE | リソースの削除 |
| PATCH | リソースの一部変更 |
| HEAD | リソースのメタ情報の取得 |
GET
ブラウザのA(アンカー)要素を使ったリンクはすべてGETとして扱われる。URIで指定されたリソース（＝情報）を取得するために用いる。GETを使ったアクセスで、サーバ上のリソースが変更されることは基本的にありえない。
POST
指定したURIに属する新しいリソースを送信する。つまり新しい情報を登録するために利用する。情報の変更や削除のためのメソッドは別途あるが、HTML4.0のFormではmethod属性に指定できるのがGETとPOSTだけのため、ブラウザからFormを使って送信する場合には、削除や更新も含めてすべての処理をPOSTでやるのが一般に普及している。
PUT
POSTと同様にサーバ側の情報を更新するためのメソッドだが、もしそのURIのリソースがすでに存在しているものの場合、PUTはそれを修正する用途で使う。またPOSTはURIの配下に新しいデータを登録し、PUTは指定したデータそのものを更新する。
上記の図はわかりやすかったため、本書32ページより引用。
DELETE
URIで指定したリソースを削除する。
PATCH
PUTと同じく、指定したリソースを更新するために利用するメソッドだが、全てを変更するのではなく、一部を変更することを明示したメソッド。
エンドポイントを設計する上での注意点
複数形の名詞を利用する
そもそもなぜ名詞なのか
→ HTTPのURIがそもそもリソースを表すものであるため。HTTPのメソッドが動詞を表すものなので、URIの名詞とHTTPメソッドの動詞という組み合わせが最もシンプルに行いたいことを表すことができる。
データベースのテーブル名が複数形を用いるのが適切であるのと同様に、データの集合を表しているので複数形を利用する。
利用する単語に気をつける
例えば何かを探す場合の単語として、findかsearchがあるが、基本APIで使用されるのはsearchである。
このように似た単語でどちらを利用しようか迷う場合は、下記サイトなどを参考にしてよく使われている単語を使うようにすると良い。
スペースやエンコードを必要とする文字を使わない
URIでは利用できない文字は、パーセントエンコーディングと呼ばれる%E3%81%82のような文字コードを%付きで表した表記方法になるが、これだとエンドポイントがどのようなものなのかひと目ではわからなくなる。またスペースはURI中では+に変換されるので避けるようにする。
単語をつなげる必要がある場合はハイフンを利用する
URI中のホスト名 (ドメイン名）はハイフンは許可されているもののアンダースコアは使えず、ホスト名は大文字小文字の区別がなく、ドットは特別な意味を持つため、ホスト名と同じルールでURI全体を統一しようとするとハイフンでつなぐのが最も適している。
以上です！また続編書きます！
Discussion