CR-FASTAPI-000: API Inventory - 完了レポート

実装日時

2024年12月初旬（当時の詳細不明）

概要

目的

NexusCore リポジトリ内の既存 HTTP API（主に Flask ベース）を全て棚卸しし、public / internal / 廃止候補に分類して一覧化する。FastAPI 移行の優先順位を決定するためのベースラインを確立する。

ゴール

  • リポジトリ全体から Flask ベースのルーティング定義を探索
  • 各ルートについて、HTTP method、path、module/file path、handler function、認証方式、用途分類を抽出
  • docs/api/APIインベントリ.md に Markdown テーブルとして一覧化

原則

  • 既存コードの挙動は変更しない（棚卸しとドキュメント追加のみ）
  • 分類に迷う場合は “internal” とし、備考に理由を記載
  • FastAPI 移行は行わず、「現状の API の見える化」のみを行う

実装ステップ

Step 1: Flask ルーティング定義の探索

実施内容:

  • リポジトリ全体から Flask ベースのルーティング定義を探索
  • @app.route, @blueprint.route, flask.Blueprint(...).route などのパターンを検索
  • 個別に実装されたルート関数も漏らさず抽出

確認対象ファイル（推測）:

  • src/nexuscore/api/server.py
  • src/nexuscore/webapp/api_external.py
  • src/nexuscore/webapp/api_badges.py
  • src/nexuscore/webapp/views_*.py
  • src/nexuscore/agents/constitutional_council_agent.py

Step 2: API 情報の抽出

実施内容:

  • 各ルートについて以下の情報を抽出：
    • HTTP method (GET/POST/PUT/DELETE/…)
    • path (例: “/api/execute”, “/api/projects”, “/health”)
    • module / file path (例: “src/nexuscore/api/server.py”)
    • handler function 名 (例: “execute_task”)
    • 認証の有無・方式 (“no auth”, “API key”, “session” など)
    • 用途分類（”public”, “internal”, “deprecated” or “candidate_for_removal”）
    • 備考（Gradio/UI からのみ呼ばれている、Webhook 入口など）

Step 3: ドキュメント作成

実施内容:

  • docs/api/APIインベントリ.md を新規作成
  • 見出し構成:

    • API Inventory (Flask baseline)

    • Public endpoints

    • Internal endpoints

    • Deprecated / removal candidates

  • 各分類ごとに Markdown テーブル形式で一覧化

作成ファイル:

  • docs/api/APIインベントリ.md - API 棚卸し結果ドキュメント

変更ファイル一覧

新規作成ファイル

  • docs/api/APIインベントリ.md - API Inventory ドキュメント（Public / Internal / Deprecated の分類と一覧）

変更ファイル

  • なし（既存コードの挙動は変更していない）

動作確認結果

静的解析結果

  • リンターエラー: なし（ドキュメントファイルのみの追加のため）
  • 型チェック: 該当なし

ドキュメント確認結果

作成されたドキュメント: docs/api/APIインベントリ.md

確認項目:

  • ✅ Public endpoints セクションに 8 件のエンドポイントが記載されている
  • ✅ Internal endpoints セクションに 12 件のエンドポイントが記載されている
  • ✅ Deprecated / removal candidates セクションに 3 件のエンドポイントが記載されている
  • ✅ 各エンドポイントについて、HTTP method、path、module/file path、handler function、認証方式、備考が記載されている
  • ✅ ドキュメントが存在することを確認

コードレビュー結果

  • ✅ 既存コードの挙動に影響を与えていない（ドキュメント追加のみ）
  • ✅ 分類基準が明確に記載されている

設計上の改善点

アーキテクチャの改善

  1. API の見える化
    • 既存の Flask ベース API を体系的に整理
    • Public / Internal / Deprecated の分類により、FastAPI 移行の優先順位を明確化
  2. 移行計画の基盤確立
    • API Inventory をベースラインとして、FastAPI 移行の優先順位を決定可能に
    • 各エンドポイントの用途分類により、移行戦略を策定しやすい構造

将来の拡張性への配慮

  1. 移行状況の追跡
    • ドキュメントに「FastAPI 移行済み」の記載を追加可能な構造
    • 例: Badges API については “→ FastAPI移行済み (CR-FASTAPI-009)” と記載
  2. 継続的な更新
    • 新しいエンドポイントが追加された場合、Inventory に追記する運用を想定

コード品質の向上

  1. ドキュメント化
    • 既存の API エンドポイントの全体像を明確化
    • 開発者が API の構造を理解しやすい形式
  2. 移行作業の効率化
    • 分類ごとに移行作業を進めることで、効率的な移行が可能

既知の制約・注意事項

既存コードとの互換性

  • ✅ 既存コードの挙動には一切影響を与えていない（ドキュメント追加のみ）

制限事項やトレードオフ

  1. 分類の主観性
    • Public / Internal / Deprecated の分類は、当時の判断基準による
    • 分類に迷う場合は “internal” とし、備考に理由を記載する方針
  2. 情報の精度
    • 当時のコードベースの状態に基づいて抽出された情報
    • コードベースが変更された場合、Inventory の内容と実際のコードが不一致になる可能性

移行時の注意点

  • API Inventory は「現状の API の見える化」のみを行ったもので、FastAPI 移行は行っていない
  • 今後の FastAPI 移行作業では、この Inventory をベースラインとして使用する

次のステップ

推奨されるフォローアップアクション

  1. FastAPI 移行の優先順位決定
    • Public endpoints を優先的に移行
    • /api/v1/execute と /api/v1/status/<task_id> の移行（CR-FASTAPI-002）
    • /api/github/webhook の移行（CR-FASTAPI-003）
  2. 継続的な更新
    • 新しいエンドポイントが追加された場合、Inventory に追記
    • FastAPI 移行が完了したエンドポイントについて、Inventory に移行済みの記載を追加
  3. ドキュメントの活用
    • 移行作業の進捗を Inventory に反映
    • 移行完了後は、Inventory を移行状況の記録として活用

関連ドキュメント

まとめ

CR-FASTAPI-000 の実装により、NexusCore リポジトリ内の既存 HTTP API の棚卸しが完了しました。docs/api/APIインベントリ.md に Public / Internal / Deprecated の分類で一覧化され、FastAPI 移行の優先順位を決定するためのベースラインが確立されました。既存コードの挙動には影響を与えず、ドキュメント追加のみで完了しています。

This site uses Just the Docs, a documentation theme for Jekyll.