API設計スキルをブラッシュアップするための22のベストプラクティスの記事を読んだのでご紹介

新井公貴

2023.06.22

140

こんにちは!

今日はAPI設計についてです。API設計は、私たちが日々使用するアプリケーションの裏側で重要な役割を果たしています。

その設計がうまく行かないと、アプリケーション全体のパフォーマンスやユーザーエクスペリエンスに影響を及ぼす可能性があり、開発後半に行き詰まることがあります。


そこで、API設計スキルを次のレベルに引き上げるためのベストプラクティスを22選ご紹介します。

これ意識して!

  1. URLにケバブケースを使う: URLは読みやすさとSEOの観点からケバブケース(例:my-example-url)を使用します。
  2. パラメータにキャメルケースを使う: パラメータはJavaScriptとの親和性を保つためにキャメルケース(例:myExampleParameter)を使用します。
  3. コレクションを指す名前は複数形にする: リソースの集合を表す名前は複数形にします(例:users、products)。
  4. URLはコレクションで始まり、識別子で終わる: URLの構造は一貫性を保つために、コレクション名で始まり、特定のリソースを識別するIDで終わるようにします。
  5. リソースURLに動詞を使わない: リソースのURLは名詞を使用し、HTTPメソッド(GET、POST、PUT、DELETE)で操作を表現します。
  6. 非リソースURLには動詞を使う: リソースではなく操作を表すエンドポイント(例:/resetPassword)では、動詞を使用します。
  7. JSONのプロパティにキャメルケースを使う: JSONのプロパティ名はJavaScriptとの親和性を保つためにキャメルケースを使用します。
  8. モニタリングのためのエンドポイントを実装する: サービスの健康状態を監視するために、/health、/metricsなどのエンドポイントを実装します。
  9. リソース名にテーブル名を使わない: データベースのテーブル名をそのままリソース名にするのではなく、ビジネスロジックに基づいた名前を使用します。
  10. API設計ツールを使う: API設計とドキュメンテーションを助けるツール(例:Swagger、Postman)を活用します。
  11. バージョンに単純な序数を使う: APIのバージョン管理には単純な序数(v1、v2など)を使用します。
  12. レスポンスにリソースの総数を含める: リスト形式のレスポンスには、リソースの総数を含めることで、ページネーションなどの処理を容易にします。
  13. limitパラメータとoffsetパラメータを受け入れる: ページネーションを実装するために、リクエストで取得するリソースの数(limit)と開始位置(offset)を指定できるようにします。
  14. fieldsクエリパラメータを使う: 必要なフィールドのみをレスポンスに含めることで、データの転送量を削減します。
  15. URLに認証トークンを渡さない: セキュリティの観点から、認証トークンはヘッダーに含めるか、POSTリクエストのボディに含めます。
  16. コンテンツタイプを有効にする: サーバーはリクエストのコンテンツタイプを憶測せず、明示的に指定します(例:application/json)。
  17. CRUD機能にHTTPメソッドを使う: CRUD(Create、Read、Update、Delete)操作はそれぞれHTTPメソッド(POST、GET、PUT/PATCH、DELETE)に対応します。
  18. ネストされたリソースURLにリレーションを使う: リソース間の関係を表すために、ネストされたURLを使用します(例:/shops/2/products)。
  19. CORSをサポートする: クロスオリジンのリクエストを許可するために、CORS(Cross-Origin Resource Sharing)をサポートします。
  20. セキュリティを強化する: すべてのエンドポイントにHTTPSを適用し、データの安全性を保証します。
  21. エラーハンドリングを適切に行う: クライアントが無効または不正なリクエストを行った場合、適切なエラーメッセージとともに4xx HTTPエラーコードを返します。
  22. ゴールデンルールを守る: フラットはネストより良い、単純は複雑より良い、文字列は数字より良い、一貫性はカスタマイズより良い、という原則を守ります。

まとめ

これを読む前から意識していたこともあるかもしれませんが、再度これを読んで意識できると品質が上がること間違いなしです!


これらのベストプラクティスを実践することで、API設計スキルを向上させ、アプリケーションのパフォーマンスとユーザーエクスペリエンスを向上させることができます。


それでは、皆さんがこれらのベストプラクティスを活用して、素晴らしいAPIを設計することを願っています!

この記事をシェアする