Web API The Good Partsを読んでみて

はじめに

お世話になります、hosochinです
今回は「Web API The Good Parts」を読んでみました

読んだ感想

本書はそれほど厚くなく、サクッと読めました
API設計に関する筆者のベストプラクティスがコンパクトにまとまっていて、どれも納得できるものが多かったです
API設計で悩むことは結構あると思いますが、とくに拘りのない部分は素直に本書でオススメされている方針に従うと良さそうかなと感じました

以下に本書で挙げられていた設計ポイントの一部をピックアップしておきます

エンドポイント, リクエストの設計

  • 短く入力しやすい
    • 悪い例：/get/service/api/search
      • serviceやapiが冗長
      • getはHTTPメソッドで表現可能
    • 良い例：/search
  • 人間が読んで理解できる
    • むやみに省略された言葉を使わない
    • 悪い例：/sv/u/
      • svはserviceの略？uはuserの略？省略されていると理解できない
  • サーバ側のアーキテクチャが反映されていない
    • 悪い例：/cgi-bin/get_user.php?user=100
      • phpで書かれていることや、CGIとして動作しているんだろうということが分かりますが、利用者にとってはそんなことはどうでもいいので反映すべきでない
      • 内部のアーキテクチャを公開することはセキュリティ面でもリスク
  • ルールが統一されている
    • エンドポイントによって用語が変わったりしないこと
  • 適切なHTTPメソッドが利用されていること
  • 利用する単語が一般的であること
    • searchを使うかfindを使うかなど迷ったら、他の類似のAPIを参考にしてみる
  • 名詞は複数形を使う
    • 悪い例：/v1/user/user-id
    • 良い例：/v1/users/user-id
      • 複数形を使うことで「リソースの集合」を表すことができる
      • 複数形にすることで大きく形が変化する単語もあるため注意
  • 単語はハイフンで繋げる
  • クエリパタメータとパスパラメータを適切に使い分ける
    • リソースの位置を表すのにはパスパラメータを用いるのが一般的
    • アクセストークンなどはリソースとは無関係のためクエリパラメータが一般的
    • offset, limit, pageなどのパラメータは省略した場合デフォルトの値が利用されることが多いが、省略可能なものはクエリパラメータ

レスポンスの設計

  • データ形式はJSONがデフォルトになっていること
  • レスポンスの内容をクライアントがクエリパラメータで指定できること
    • クライアントとしては不要な情報は取得したくない、なるべくデータサイズも小さくしたい
    • クエリパラメータで指定できると使い勝手がいい
    • 提供側の都合で仕様を決めすぎないこと
  • 不要なエンベロープが入っていないこと
    • HTTPヘッダを適切に利用するなどで冗長な表現はなるべく排除する
  • レスポンスデータはなるべくフラットにすべき
    • 不要な階層は作らない
  • レスポンスデータのトップレベルは配列ではなくオブジェクトにすること
    • JSONはトップレベルにオブジェクトと配列のどちらも指定できるが…
      • オブジェクトの方が、レスポンスデータが何を示しているか分かりやすい
      • オブジェクトに統一できる
      • 個人的に思うのは、トップレベルを配列にしてあると、レスポンス内容を拡張したい時に後方互換性を保つのが難しい
      • たとえば、配列とは別にページ情報など共通的なレスポンスを追加したくなったとき、トップレベルがオブジェクトであれば変更が容易
  • 命名についてはエンドポイントの設計とだいたい同じ感じ
    • 短く分かりやすい単語
    • 省略形を用いない
    • 統一された単語
    • 単数/複数形がデータの内容と一致している
  • 適切なステータスコードが返ること
    • ぴったりくるステータスコードがなければ、200 or 400 or 500 というように「00」で終わるステータスコードを返すのがオススメ
  • ハンドリングできていないエラーがそのままクライアントに返るのはダメ絶対

バージョンニングについて

  • APIがバージョン管理されていること
  • バージョンはセマンティックバージョニングに沿っていること
  • メジャーバージョン番号がエンドポイントに入っていること（URIバージョニングされていること）
    • /v1/users のように、「v」+ メジャーバージョン番号がオススメ
    • 全ての利用者の動作に影響がないように後方互換性を維持する
    • メジャーバージョンを上げるのは最後の手段
      • 後方互換性を失う修正が必要になった場合
      • メジャーバージョンを上げたエンドポイントをリリースする
      • すでにリリース済みのエンドポイントは提供を続けること
        • 勿論、長くサービスを運用していれば、どこかのタイミングで古いバージョンを廃止する必要が出てくる
        • 事前にAPI提供の終了をアナウンスし、周知徹底しなければならない
      • マイナーバージョン以下はURIで管理しないこと
        • エンドポイントが無数に増えて維持が大変

読書API,microService

Posted by hosochin