Web API: The Good Parts 読んだ

Web API: The Good Parts

読んだ

モチベーション

• ここしばらく API を開発していたけれど，ずっと勘と経験を頼りにやっていてちょっと整理したかった
• そのために補助線として本があると便利そうという感じ

読書メモ

1章

• 第1章の最後に LSUDs (large set of unknown developers)` と `SSKDs (small set of known developers)` という概念に触れられていた
  • The Future of API Design: The Orchestration Layer で言及されている概念
  • その API がパブリックなものなのかプライベートなものなのかで設計の指針は変わりますね，みたいな感じ．
    • 重要で，ここを間違えると全然違うでしょって設計になってしまうと思う
      • あるウェブサービスがあった時，自社でアプリを作るので API 切りましょう，ってなった場合を考える
        • Twitter の API 真似してもうまくいかなさそう
• 今回私は SSKDs を対象とした API の開発者/設計者という視点で読んでた．

2章: エンドポイント設計とリクエストの形式

• 2.5 クエリパラメータの設計
  • 一覧を取得するような API で相対位置で取得するようなデザインは問題を生みやすいことが指摘されている
    • 経験的にも思うところがあり，絶対位置での指定の方がいいように思う
      • しかしそうなるとペーじゃの実装がむずい
        • ページャ，間違った発明だったのでは...
• 2.9 HATEOAS と REST LEVEL 3 API
  • HATEOAS: 次に行える行動/取得するデータなどの URI をリンクとしてレスポンスに含める
  • REST LEVEL 3: Martin Fowler 氏が REST API の設計レベルっていうのを提案してる
    • その中では最終段階の LEVEL 3 に HATEOAS 概念の導入がある
      • 著者のコメントとして，SSKDs 向け API ではいいかもしれないけど LSUDs 向け API では合わないかもねみたいなことが書いてある
        • 私もそう感じます

3章: レスポンスデータの設計

• 3.3: エンベロープは必要か
  • エンベロープ: 本来返したいコンテンツをラップする構造

エンベロープなしの例

{
  "friends": [100, 101, 102]
}

エンベロープありの例

{
  "results": {
    "friends": [100, 101, 102]
  }
}

• 著者はエラーやメタ情報は HTTP のに寄せるべきという立場
  • ステータスコードなら HTTP のステータスを使えばいいしメタ情報は HTTP ヘッダに入れれば良い
  • 僕は違う考えがあって，現代のアプリケーションで発生するエラーは多様性にあふれており，HTTP のエラーコードでは表現力が足りないと思っている
    • 過去には HTTP Status は 500 にしつつカスタムヘッダとアプリケーションレスポンスにアプリケーションのエラーコードを含めるという実装をしました
      • ヘッダだと HTTP サーバのログフォーマットへ出力を追加しやすい
    • あと HTTP としては完全に成功していて，アプリケーション起因の問題のケースで 200 を返しつつボディのエラーを付与するという実装が入ったことがある
      • これはちょっと失敗だったかもしれない...
        • どうしても warning 的なレスポンスを表現したく，しかしエラーとして監視/カウントしたくないタイプのエラー（Expected but Unacceptedな奴．例えば会議室の予約システムで予約しようとした時間にすでに予定があるとか）ではあった
        • 4xx系のエラーステータス使えば? みたいな話はあるけど、「えっこれ別にエージェントが悪いわけじゃないですよね」みたいなモゴモゴした気持ちになる、上の例だと既に予定があるかどうか厳密には登録するまでわからないわけですし……
    • アプリケーション固有のエラーコードがあると，エージェントにより適切な情報を伝えられるので，その先にいるユーザやシステムが適切にハンドルできるようになる
      • と言っても全てのエラーにエラーコード降るのはコストがかかるのもあり，汎用エラーみたいなのは多用してしまったが...
  • 実際の例でいうとParse.comのレスポンスはエンベロープを採用していて、結構便利だったので採用したみたいなところがあります

4章: HTTPの使用を最大限利用する

• キャッシュの話丁寧に説明されていて良かった
• 独自のHTTPヘッダ定義するとき，最近は X- つけなくてもいいんじゃない? みたいな RFC が出てるらしく，へーって思った
  • RFC とはいえ "Best Current Practice" のやつだけど
    • 余談なんですが， X- は全部空いてると思いきや X-Content-Type-Options と X-Frame-Options が IANA で抑えられてるの知らなかった

5章: 設計変更をしやすい Web API を作る

• むずいよねえ
• オーケストレーション層を作って吸収する話は良かった，規模が大きくなってくるとそう言った動きも重要そう
• 僕自身の経験を振り返ると以下の取り組みがあった
  • URI のパスレベルでバージョンを切る
    • /v1/users/:user_id/profile みたいな
    • レスポンスフォーマットのプロパティはだいたい追加は簡単，削除はむずい
    • リクエストフォーマットの必須項目追加は辛い
      • 必然的にオプションとして追加しつつデフォルト値を入れていくスタイルになりがち

6章

• JSON ハイジャックの話が印象深かった
• その他APIにおけるセキュリティのエッセンスが詰まってる感じで良かった
  • ヘッダ周りとかは割と抜けてることあるので確認しておきたい

---

エンベロープと HTTP Status との付き合い方はまだちょっと考えが足りないのと思うので折を見て考えたい