外部AI連携向けにAPIのレスポンスとエラー形式を統一する

[komagata]

機能の説明

外部AIエージェントがAPIを安定して扱えるように、APIの成功レスポンスとエラーレスポンス形式を統一する。

現状、APIによって以下のようなばらつきがある。

• 成功時に empty body を返すAPIがある
• HTML partial を返すAPIがある
• validation error が head :bad_request のみで詳細が返らないAPIがある
• エラーJSONのキーやステータスコードが統一されていない

統一方針の候補:

• 成功時は作成・更新対象のリソースJSONを返す
• 削除時は {} または削除対象IDなど、統一した形式で返す
• validation error は 422 Unprocessable Entity と errors JSONを返す
• 権限不足は 401 / 403 を用途に応じて使い分ける
• 存在しないリソースは 404 と JSON エラーを返す

何故この機能が必要なのか

pjord/hermes agent がAPIを使って生徒サポートやメンター業務を行う場合、レスポンスの形式がばらついていると処理分岐が増え、失敗時の復旧も難しくなる。

外部クライアント向けAPIとして、成功・失敗の形式を揃える必要がある。

受け入れ条件

• 外部AI連携で使う主要APIのレスポンス形式を棚卸しする
• 作成・更新・削除APIの成功レスポンス方針を決める
• validation error、権限不足、not found、重複などのエラー形式を決める
• 既存クライアントへの影響を確認し、必要なら段階的に移行する
• 少なくともコメント、回答、チェック、リアクション、日報、提出物まわりで統一方針を適用する
• integration test で代表的な成功・失敗レスポンスを確認する

関連コード

• app/controllers/api/base_controller.rb
• app/controllers/api/comments_controller.rb
• app/controllers/api/answers_controller.rb
• app/controllers/api/checks_controller.rb
• app/controllers/api/reactions_controller.rb
• app/controllers/api/reports_controller.rb
• app/controllers/api/products_controller.rb
• test/integration/api/*