オリジナルソース: Compose your API surface with Data API builder custom paths
Data API Builder の新しい複合 REST パスサポートは、小さな設定改善のように見えるかもしれないが、実際には長年の API 設計上の緊張を解決する: データベーストポロジがパブリックエンドポイント設計に漏れ出す問題である。
デフォルトのエンティティベースのルートはクイックスタートには最適である。長期的なプロダクト API にはしばしば不適切である。実際のシステムには、ビジネス概念、所有権境界、消費者のメンタルモデルに一致するルート構造が必要である。
だからこそ、この DAB の変更が重要なのである。生成された API の利便性を維持しながら、よりクリーンなドメインファーストの表面を提示できる。
私の意見を明確に述べる:本番環境で API パス構造が生のテーブル名を反映している場合、通常はクライアントの明確さを犠牲にしてバックエンドの利便性を最適化していることになる。
カスタムパスにより、チームはセールス、請求、サポート、パートナー固有の表面など、より良い境界をモデル化できる。これは適切な API ガバナンスを置き換えるものではないが、DAB ユーザーにルート設計をプロダクト言語と整合させる実用的な方法を提供する。
この機能を採用するチームへの実践的ガイダンス
- アドホックにパスを追加する前に命名ポリシーを定義する。一貫性のないサブセグメントは長期的なノイズになる。
- エンドポイントを境界付けられたコンテキストにマッピングし、組織図にはマッピングしない。チームは変わるが、ドメインセマンティクスは安定しているべきである。
- パス構造をバージョニング戦略の一部として扱い、破壊的変更を明示的に文書化する。
- カスタムルート構造に沿って認可動作を検証し、ルートの明確さがセキュリティの明確さと対になるようにする。
DAB 全般について私が評価するのはレバレッジモデルである: 反復的なコントローラーコードを書くことなく、ページネーション、フィルタリング、プロジェクション、その他のエンドポイント機構を得られる。カスタムパスは、API アーキテクトからの最大の反対意見のひとつを減らすことで、そのレバレッジをよりプロダクション対応にする。
ひとつの注意点がある。パス構成が容易なため、生成が簡単だからといって、チームがあまりに多くをあまりに早く公開してしまう誘惑にかられる可能性がある。ガードレールは依然として重要である: エンティティの公開は意図的に行い、ポリシーを中央で適用し、内部スキーマ実験から偶発的なパブリック契約を構築しないようにする。
デリバリー圧力下にある .NET 組織にとって、この機能は規律を持って使用すれば生産性向上の鍵となる。手作りの API レイヤーよりも速く進めながら、一貫性のあるビジネスフレンドリーなエンドポイント表面を維持できる。
結論: DAB カスタムパスは URL の美化ではない。生成されたエンドポイントの運用効率を維持しながら、API 設計の意図を取り戻すことである。
