なにこれ
Web API The Good Parts
という本を読んだメモ
2章
URIの設計の原則
短く入力しやすいURI
- 無駄な名前を含めるな(get_ とか service_とか
人間が呼んで理解できるURI
- 省略語を使うな(addrとかsvとか
大文字小文字が存在してないURI
- product id 1~100はこのAPI、101以降はこのAPIみたいなことをするな
改造しやすい（Hackable）なURI
サーバ側のアーキテクチャが反映されてないURI（.phpみたいな）
ルールが統一されたURI
覚えやすくどんな機能を持つURIなのかがひと目で分かる
エンドポイントには極力動詞をつけない。get post putでどの処理か分かるので
URLはハイフン繋ぎが良い。理由はgoogleのSEO的にハイフンだと別単語で認識する。アンダースコアは繋げるから(ただしjson apiは知らん、フロントの話っぽいから)
SSKDs
Small Set of Known Developers
LSUDs
Large Set of Known Developers
覚えやすく機能が一目でわかるエンドポイントに
適切なhttpメソッドを使え
英単語、単数形と複数形に注意
3章
キャメルかスネークか統一しろ！混ぜるな危険
user registration data timeは
registerdAtにできる。userリソースだからuserいらない
性別は文字列で表現が大多数
レスポンスはできるだけフラットに！
エラーの形式を統一、クライアントがエラー詳細を理解できるように
web apiチェックリスト
- URIが短く入力しやすい
- URIが人間が呼んで理解
- URIが小文字のみ
- URIが改造しやすいか
- URIのルールは統一されてるか
- 適切なHTTPメソッドを利用しているか
- URIで利用する単語は、多くのAPIで同じ意味に利用されているものを選んでいるか
- URIで使われている名詞は複数形か
- URI中にスペースやエンコードを必要とする文字が入ってないか
- ページネーションは適切に設計されてるか
- データ形式の指定には、クエリパラメーターを使う方法をサポートしているか
- response.bodyの内容はクライアントから指定できるか
- データの構造は可能な限りフラットになってるか
- response.bodyとして多くのAPIで同じ意味に利用されてる一般的な単語を選んでるか
- response.dataはなるべく少ない単語数で表現してるか
- 複数の単語を連結する場合、API全体を通して統一してあるか
- response.bodyで変な省略形を使用していないか
- response.body名は単数形 or 複数形と合ってるか
- error時にはクライアントが原因を切り分けられる情報を含んでるか
- 適切なステータスコードが返るか
- メンテナンス時には503を返すようになってるか
- APIのversionは管理されているか