Skip to main content

API設計とバージョニング

RESTful API ベストプラクティス​

.NET (ASP.NET Core) でRESTful APIを構築する際の主要な原則です。

リソース指向​

  • 名詞を使用する (/api/users vs /api/getUsers)
  • 適切なHTTPメソッドを使用する (GET, POST, PUT, PATCH, DELETE)
  • 階層構造を活用する (/api/users/{id}/orders)

ステータスコード​

適切なHTTPステータスコードを返却します。

  • 200 OK: 成功
  • 201 Created: リソース作成成功
  • 204 No Content: 成功したが返すコンテンツがない (DELETEなど)
  • 400 Bad Request: クライアントエラー
  • 401 Unauthorized: 未認証
  • 403 Forbidden: 権限不足
  • 404 Not Found: リソース不在
  • 500 Internal Server Error: サーバーエラー

冪等性 (Idempotency)​

  • GET, PUT, DELETE は冪等であるべきです（何度実行しても結果の状態が変わらない）。

APIバージョニング戦略​

APIの変更がクライアントに影響を与えないように、バージョニングを適切に行います。ASP.NET Coreでは Asp.Versioning.Http (旧 Microsoft.AspNetCore.Mvc.Versioning) がよく使われます。

主な戦略​

  1. URLパス: /api/v1/products
    • 最も一般的で分かりやすい。
  2. クエリパラメータ: /api/products?api-version=1.0
    • URL構造を変えたくない場合に有効。
  3. ヘッダー: X-Version: 1.0
    • URLをクリーンに保てるが、キャッシュ制御が複雑になる場合がある。

OpenAPI / Swagger / Scalar​

API仕様を記述・ドキュメント化するための標準です。

OpenAPI (Swagger)​

ASP.NET Coreでは Swashbuckle.AspNetCore や NSwag を使用して、コードからOpenAPI仕様書 (swagger.json) を自動生成するのが一般的です。

Scalar​

Scalarは、よりモダンで高速、かつ美しいAPIリファレンスを生成するツールです。Swagger UIの代替として注目されています。 .NETでも Scalar.AspNetCore などのライブラリを通じて統合可能です。

特徴:

  • 高速なレンダリング
  • 優れた検索機能
  • モダンなUIデザイン
  • 多言語のクライアントコード生成
// Program.cs での統合例 (イメージ)
app.MapScalarApiReference();

gRPC vs REST​

特徴REST (Web API)gRPC
プロトコルHTTP/1.1 または HTTP/2HTTP/2
データ形式JSON (テキスト)Protobuf (バイナリ)
パフォーマンス比較的遅い (テキスト解析)高速 (バイナリ、多重化)
ブラウザ対応容易gRPC-Webが必要
ユースケース公開API、CRUD操作マイクロサービス間通信、高パフォーマンス要件

.NETはgRPCをファーストクラスでサポートしており、Grpc.AspNetCore パッケージを使用して簡単にサーバー/クライアントを実装できます。

GraphQL in .NET​

GraphQLは、クライアントが必要なデータを正確に指定して取得できるクエリ言語です。

Hot Chocolate​

.NETにおける代表的なGraphQLサーバーライブラリです。

  • Schema First / Code First: 両方のアプローチをサポート。
  • Filtering / Sorting: 強力なクエリ機能。
  • Banana Cake Pop: 付属のIDEでクエリをテスト可能。

RESTとの使い分け​

  • REST: リソースが明確で、キャッシュを活用したい場合。
  • GraphQL: クライアントによって必要なデータ構造が異なり、オーバーフェッチ/アンダーフェッチを防ぎたい場合。

ベストプラクティス​

  1. 契約（Contract）を明確にする: APIの入力と出力（DTO）は明確に定義し、内部ドメインモデルを直接公開しないようにしてください。
  2. 一貫性を保つ: エンドポイントの命名規則、エラーレスポンスの形式、日付の形式（ISO 8601推奨）などをAPI全体で統一してください。
  3. ドキュメントを自動生成する: OpenAPI (Swagger) や Scalar を使用して、コードから常に最新のドキュメントを生成し、クライアント開発者と共有してください。
  4. 非互換な変更を避ける: 既存のクライアントを壊さないように、変更が必要な場合は新しいバージョンを作成するか、後方互換性を維持してください。
  5. 適切な通信プロトコルを選択する: 外部公開用にはREST、内部マイクロサービス間にはgRPCなど、要件に応じて適切なプロトコルを選択してください。

まとめ​

  • REST: 標準的で汎用性が高い。Scalarなどを活用してドキュメントを充実させる。
  • gRPC: 内部通信やパフォーマンス重視の場面で採用。
  • GraphQL: 柔軟なデータ取得が必要なフロントエンド向けBFFなどで有効。
  • バージョニング: 初期の段階から戦略を決定しておくことが重要。