API実装状況 - rfdnxbro/trends-laravel GitHub Wiki

API実装状況

概要

Laravel Trendsプロジェクトでは、企業の技術コミュニティ影響力を分析するためのRESTful APIを提供しています。 すべてのAPIエンドポイントが実装済みで、React フロントエンド開発やサードパーティ連携に利用可能です。

フロントエンド統合状況 🎨

React アプリケーション ✅ 実装完了

  • React 19 + TypeScript + Vite: モダンな開発環境
  • React Router v7: SPA ルーティング
  • React Query v5: APIデータ管理・キャッシュ
  • Tailwind CSS v4: レスポンシブUI
  • Axios: HTTP通信

実装済みページ

  • ✅ ダッシュボード: / - 統計情報・上位企業ランキング表示
  • ✅ 企業詳細: /companies/{id} - 企業情報・記事一覧・ランキング履歴

API統合状況

API種別 React統合 説明
ダッシュボード統計 ✅ /api/rankings/statistics - 期間別統計情報（総企業数・記事数・エンゲージメント数）
上位企業ランキング ✅ /api/rankings/1m/top/10 - 1ヶ月期間のトップ10企業表示
企業詳細情報 ✅ /api/companies/{id} - 企業詳細・記事一覧・ランキング履歴
企業検索 🔄 実装準備中

実装済みAPI一覧

1. 企業ランキングAPI 📊

期間別の企業影響力ランキングを提供します。

エンドポイント 説明 実装状況
GET /api/rankings/periods 利用可能期間タイプ一覧 ✅
GET /api/rankings/statistics ランキング統計情報 ✅
GET /api/rankings/{period} 期間別ランキング（daily/weekly/monthly） ✅
GET /api/rankings/{period}/top/{limit} 上位N件の企業ランキング ✅
GET /api/rankings/{period}/risers 順位上昇企業一覧 ✅
GET /api/rankings/{period}/fallers 順位下降企業一覧 ✅
GET /api/rankings/{period}/statistics 順位変動統計 ✅
GET /api/rankings/company/{company_id} 特定企業のランキング情報 ✅

詳細ドキュメント: /storage/api-docs/api-docs.json (OpenAPI仕様)

2. 企業詳細API 🏢

個別企業の詳細情報と分析データを提供します。

エンドポイント 説明 実装状況
GET /api/companies/{company_id} 企業詳細情報 ✅
GET /api/companies/{company_id}/articles 企業の記事一覧（ページネーション） ✅
GET /api/companies/{company_id}/scores 影響力スコア履歴 ✅
GET /api/companies/{company_id}/rankings 企業のランキング情報 ✅

詳細ドキュメント: /storage/api-docs/api-docs.json (OpenAPI仕様)

3. 記事API 📰

記事の詳細情報と一覧取得機能を提供します。

エンドポイント 説明 実装状況
GET /api/articles 記事一覧（企業・プラットフォーム別フィルタ、ページネーション） ✅
GET /api/articles/{id} 記事詳細情報（タイトル・URL・著者・ブックマーク数・企業情報） ✅

詳細ドキュメント: /storage/api-docs/api-docs.json (OpenAPI仕様)

4. 検索API 🔍

企業・記事の横断検索機能を提供します。

エンドポイント 説明 実装状況
GET /api/search/companies 企業名・ドメイン・説明文での企業検索 ✅
GET /api/search/articles 記事タイトル・著者名での記事検索 ✅
GET /api/search 企業・記事の統合検索 ✅

詳細ドキュメント: /storage/api-docs/api-docs.json (OpenAPI仕様)

API共通仕様

認証

  • 現在は認証不要（パブリックAPI）
  • 将来的にトークンベース認証を実装予定

レート制限

  • 制限: 60リクエスト/分
  • ヘッダー: X-RateLimit-Limit, X-RateLimit-Remaining

キャッシュ

  • 期間: 5分間
  • 対象: 全検索結果とランキングデータ
  • 戦略: Redis Cache

エラーハンドリング

{
  "error": "エラーメッセージ",
  "details": {
    "field": ["詳細なエラー情報"]
  }
}

レスポンス形式

{
  "data": {
    // メインデータ
  },
  "meta": {
    // メタデータ（ページネーション、統計等）
  }
}

テスト状況

Feature テスト

  • 企業ランキングAPI: 8個のテストケース ✅
  • 企業詳細API: 4個のテストケース ✅
  • 検索API: 12個のテストケース ✅

Unit テスト

  • 企業ランキングサービス: 5個のテストケース ✅
  • 企業影響力スコアサービス: 3個のテストケース ✅
  • 検索コントローラ: 7個のテストケース ✅

カバレッジ

  • コントローラー: 100%
  • サービス層: 95%
  • リソース層: 100%

パフォーマンス

レスポンス時間（平均）

  • ランキングAPI: ~120ms
  • 企業詳細API: ~80ms
  • 検索API: ~150ms

データ量

  • 企業データ: 500+ 社
  • 記事データ: 10,000+ 件
  • ランキングデータ: 日次更新

今後の拡張予定

  • 認証機能: JWT トークンベース認証
  • フィルタリング強化: 技術スタック・企業規模での絞り込み
  • WebSocket API: リアルタイム更新通知
  • 統計API: より詳細な分析データ
  • エクスポートAPI: CSV/JSONでのデータエクスポート
  • 機械学習API: トレンド予測・レコメンデーション
  • 外部連携API: Slack・Teams通知
  • アナリティクスAPI: 利用状況分析

利用例

企業ランキング取得

curl https://api.trends.example.com/api/rankings/weekly?limit=10

企業検索

curl "https://api.trends.example.com/api/search/companies?q=Google&limit=5"

記事検索（フィルタ付き）

curl "https://api.trends.example.com/api/search/articles?q=React&days=7&min_bookmarks=50"

開発者向け情報

ローカル開発

  1. APIドキュメント確認: /storage/api-docs/api-docs.json (OpenAPI仕様)
  2. テスト実行: php artisan test
  3. APIルート確認: php artisan route:list --path=api

デバッグ

  • ログ: storage/logs/laravel.log
  • クエリログ: Laravel Telescopeで確認
  • パフォーマンス: Laravel Debugbarで分析

関連ドキュメント