はじめに
WebAPIについて学ぼうと思い、学習を始めたのでメモ。
丸写しにならないよう、章ごとに個人的なポイントをまとめていく感じにしようと思います。
1章 Web APIとは何か
- 現在はWebAPIを前提としたサービスが広く普及しています。
- WebAPIは、公開する範囲によって、求められる設計も変わってきます。
- 公開したAPIは、利用者のことを考えると簡単に変更できない場合もあるので、利用しやすい設計が重要になってきます。
- RESTと呼ばれる考え方が存在します。
- よいAPIを設計するための指針になりますが、必ずしも徹底する必要はないと考えています。
- APIの公開範囲や、実現すべきユースケースを優先して設計をしていくことが重要です。
2章 エンドポイントの設計とリクエストの形式
- エンドポイントは人間が理解でき、技術に依存しないように設計するべきです。
- 単語が浮かばない場合は、APIとしてのデファクトを検索し、それに合わせるとよいです。
- エンドポイントのスラッシュ内は、できるだけ1単語かつ小文字にすべきです。
- 複数の単語を連結する場合、キャメルケースなのかスネークケースなのか、全大文字は許容するかなど、検討項目が増えます。
- 結果として、利用しやすさに悪影響を与えてしまいます。
- エンドポイントはリソースを指すようにし、操作方法はHTTPメソッドが担当するようにします。
- エンドポイントにエンコード文字列などが入らないようにします。
- エンコード文字列が含まれると、人間が読むために一苦労します。
- 検索には、クエリパラメータを利用します。
- IDを指定してのリソースの取得は、エンドポイントで行うよう区別するとよいと思います。
- ページングや、limit/offsetなどを用いて、適当なデータ量を返却するようにします。
- 一覧取得の場合に、大量のデータを返却するのは、トラフィックに影響を与えます。
- 公開範囲によって、エンドポイント設計は粒度などが左右されることを理解します。
- 内部用APIであれば、デファクトに必ず従うこともないです。利用者を意識したエンドポイントを意識しましょう。
3章 レスポンスデータの設計
- レスポンスのデータ形式は、特に指定がなければデファクトであるJSONを指定するとよいと思います。
- 返却したい情報は、適切な場所に格納して返却するように心がけます。（HTTPステータスコード、ヘッダ、ボディ etc.)
- HTTPステータスは様々な種類があるので、結果の概要を表現できるものを選びます。
- 例外として、結果を隠ぺいしたい場合もあると思います。その場合はどのステータスにするのかを検討しましょう。
- ボディは、オブジェクトで包んだり、データ名を工夫して、何を表現しているのか誤解を生まないように設計すべきです。
- エラーメッセージは、エラーコードを使う、開発者用のメッセージを持たせるなど、開発者がエラー原因を特定できるような仕組みを用意すべきです。
- ユーザ向けメッセージと、開発者向けメッセージは違うと思いますので。
- エラーの仕組みはAPI側では統一し、クライアント側でハンドリングしやすい状態を保ちます。
- 404はhtmlで返却されちゃう とかないように。
4章 HTTPの仕様を最大限利用する
- 仕様はRFCを見る。
- HTTPがエンベロープとしての役割を担っているので、レスポンスデータにエンベロープを用ない方が効率的。
- 3章でも述べていますが、レスポンスのHTTPスタータスコードは適切に選択しましょう。
- 適切なコードを返却することで、クライアント側が何をすればよいのかを分岐できるようになります。
- レスポンスの効率を上げるために、キャッシュは有効利用しましょう。
- キャッシュの範囲、有効期限などを考慮する必要があります。
- キャッシュの有効期限の仕組みは、RFC 7234 では以下の２種類が定義されています。
| 仕組み | 内容 |
|---|---|
| Expiration Model (期限切れモデル) | 予めキャッシュに有効期限を格納しておき、有効期限が過ぎていたら実データを再取得する仕組み |
| Validation Model (検証モデル) | 今保持しているキャッシュが最新であるかを問い合わせする仕組み |
5章 設計変更をしやすいWeb APIを作る
- APIはバージョンで管理し、後方互換性に注意して修正を行う必要があります。
- セマンティックバージョニング(メジャーバージョン.マイナーバージョン.リビジョン)が一般的。
- メジャーバージョンはURIに含めるのが一般的です。
- クエリパラメータに含める方法もありますが、省略時の挙動を考慮する必要があります。
- APIの公開終了は、利用者のことを考えて慎重に行う必要があります。
- 並行稼働期間を設ける。
- 告知をする。
- 廃止後にどういった挙動にするかを考える(410を返却するのか、エラーメッセージを返すのかなど)
6章 堅牢な Web APIを作る
- 本章の内容はセキュリティに関する一例なので、これを守れば100％オッケー！ではないです。
- 参考にした上で、最新の動向に照らし合わせて、最適な対策を行うように心がけましょう。
- 個人情報など、漏洩してはいかない情報を取り扱う場合は、HTTPS通信を利用する。
- どんな攻撃が存在するのかを知った上で、防御策を知るとよいです。
- XSSとか、XSRFとか。
- ヘッダにはセキュリティ強化用の道具が多くあるので、活用していきましょう。
-
X-Content-Type-Optionsなど。
-
- 大量アクセスを防ぐ方法として、レートリミットを設ける方法があります。
おわりに
- URIの考え方は常日頃悩みどころだったので、今後の設計などに取り入れていけたらいいなーと思いました。
- 困ったらデファクトスタンダードにしましょう っていうのはその通りだなあと。。。
- セキュリティに関してはまだ知識不足なところがあるので、実例調べつつもう少し深堀りしていきたいですね。
以上です。お疲れ様でしたー。