【要約】API設計 - RESTでは表現しにくい操作を、どう設計するか [Qiita_Trend] | Summary by TechDistill
> Source: Qiita_Trend
Execute Primary Source
// Problem
API開発者が、RESTの厳格なリソース指向に基づいた設計を行おうとする際、実務的なビジネスロジックとの乖離に直面する。CRUDモデルに無理に当てはめようとすることで、以下のような問題が発生する。
- ・状態遷移のバリデーションが複雑化し、保守性が低下する。
- ・複数リソースにまたがる操作の、適切なエンドポイントが不明確になる。
- ・GETリクエストによる意図しないデータ更新（副作用）のリスクが生じる。
- ・画面表示のために大量のリクエストが必要となり、レイテンシが悪化する。
// Approach
設計者は、RESTの教条的な遵守よりも、ビジネス要件とシステムの安定性を優先するアプローチを取る。具体的には、以下の4つの手法を用いて設計の柔軟性を確保する。
- ・アクションエンドポイント：
POST /orders/1/cancelのように、操作をリソースではなく「行為」として定義する。 - ・独立したリソース化：送金のように、特定のリソースに属さない操作を
POST /transfersとして切り出す。 - ・操作の分離：取得（GET）と更新（POST）を明確に分け、副作用による不整合を防ぐ。
- ・集約エンドポイントの導入：BFF的な発想で、複数リソースを一度に返す専用エンドポイントやGraphQLを活用する。
// Result
これらの設計手法を導入することで、開発チームは場当たり的な設計を避け、一貫性のあるAPIを提供できる。具体的な成果は以下の通りである。
- ・ビジネスルールがサービス層に明確に閉じ込められ、保守性が向上する。
- ・キャッシュやプリフェッチによる意図しないデータ更新のリスクが排除される。
- ・モバイル環境等において、リクエスト回数の削減によるレスポンス性能の向上が見込める。
- ・チーム内で「逃げ道」を事前に合意することで、設計判断の迷いが減少する。
Senior Engineer Insight
> RESTの教条主義は、大規模開発において設計の硬直化を招く。本記事が示す「アクションエンドポイント」や「BFF」への逃げ道は、実戦における必須知識だ。特に状態遷移の制御や、モバイル環境でのレイテンシ対策は、システムの信頼性とUXに直結する。ただし、場当たり的なエンドポイント増殖はAPIの複雑性を高めるため、チーム内での命名規則や設計指針の策定が不可欠である。