api-builder

API Builder - API 開発ワークフローの全体像

概要

このスキルは、API アーキテクト、インテグレーションスペシャリスト、ドキュメントの専門家を連携させ、API 開発をエンドツーエンドで支援します。API の要件を、包括的な設計、ドキュメント、テスト、インテグレーション機能を備えた本番環境対応の API に変換します。

主な機能：

• 🏗️ マルチプロトコル API 設計 - RESTful API、GraphQL、gRPC、WebSocket の実装
• 📚 包括的なドキュメント - API ドキュメントの自動生成、インタラクティブなテスト、開発者向けガイド
• 🔧 インテグレーションアーキテクチャ - API ゲートウェイ、ミドルウェア、サードパーティサービスとのインテグレーション
• 📊 API 分析と監視 - 使用状況の追跡、パフォーマンスの監視、エラー分析
• 🛡️ API セキュリティとガバナンス - 認証、レート制限、API ライフサイクル管理

このスキルを使用する場面

最適な用途：

• RESTful API の設計と実装
• GraphQL スキーマの開発とリゾルバーの実装
• API ゲートウェイのセットアップとミドルウェアの設定
• API ドキュメントの生成と開発者ポータルの作成
• API インテグレーションパターンとサードパーティサービスとの接続
• API のバージョン管理とライフサイクル管理

使用例：

• 「[application] 用の REST API を設計して実装する」
• 「[features] を備えた GraphQL API を作成する」
• 「[middleware] を備えた API ゲートウェイをセットアップする」
• 「包括的な API ドキュメントを生成する」
• 「[service] との API インテグレーションを実装する」

API 開発の専門家パネル

API アーキテクト（API 設計とアーキテクチャ）

• 重点分野：API 設計パターン、プロトコルの選択、アーキテクチャ上の意思決定
• 手法：RESTful 設計、GraphQL スキーマ設計、API コンポジション
• 考慮事項：スケーラビリティ、保守性、開発者エクスペリエンス、パフォーマンス

インテグレーションスペシャリスト（API インテグレーションとミドルウェア）

• 重点分野：API ゲートウェイ、ミドルウェア、サードパーティとのインテグレーション
• 手法：API コンポジション、サービスメッシュ、イベント駆動型アーキテクチャ
• 考慮事項：レイテンシ、信頼性、セキュリティ、監視

ドキュメントの専門家（API ドキュメントと開発者エクスペリエンス）

• 重点分野：API ドキュメント、開発者ポータル、インタラクティブなテスト
• 手法：OpenAPI/Swagger、GraphQL ドキュメント、API テストフレームワーク
• 考慮事項：開発者エクスペリエンス、ドキュメントの正確性、見つけやすさ

API セキュリティスペシャリスト（API セキュリティとガバナンス）

• 重点分野：API セキュリティ、認証、認可、ガバナンス
• 手法：OAuth 2.0、API キー、レート制限、脅威からの保護
• 考慮事項：設計段階からのセキュリティ、コンプライアンス、使いやすさ

パフォーマンスエンジニア（API の最適化と監視）

• 重点分野：API パフォーマンス、キャッシュ、監視、分析
• 手法：レスポンスの最適化、キャッシュ戦略、負荷分散
• 考慮事項：レスポンス時間、スループット、リソース使用率

API 開発ワークフロー

フェーズ 1：API 要件の分析と設計計画

使用する場面：API 開発または API のモダナイゼーションを開始するとき

使用ツール：

/sc:analyze api-requirements
API Architect: API design requirements and constraints
Integration Specialist: integration points and dependencies
Documentation Expert: documentation requirements and developer needs

作業内容：

• ビジネス要件を分析し、API 仕様に落とし込む
• API プロトコルとアーキテクチャパターンを特定する
• API コントラクトとデータモデルを定義する
• インテグレーションポイントと外部依存関係を計画する
• API ガバナンスとバージョン管理戦略を確立する

フェーズ 2：API アーキテクチャとプロトコルの設計

使用する場面：API の構造を設計し、プロトコルを選択するとき

使用ツール：

/sc:design --type api restful-architecture
/sc:design --type graphql schema
API Architect: comprehensive API design and protocol selection
Integration Specialist: integration architecture and patterns

作業内容：

• API アーキテクチャを設計し、プロトコルを選択する（REST/GraphQL/gRPC）
• API 仕様とデータコントラクトを作成する
• エンドポイントの構造とリソース間の関係を設計する
• API コンポジションとオーケストレーションのパターンを計画する
• エラー処理とレスポンス形式を定義する

フェーズ 3：API の実装と開発

使用する場面：実際の API コードとビジネスロジックを記述するとき

使用するツール：

/sc:implement api-endpoints
API Architect: API implementation patterns and best practices
Integration Specialist: middleware and integration implementation
API Security Specialist: security controls and authentication

作業内容：

• API エンドポイントとビジネスロジックを実装する
• 認証、検証、エラー処理のためのミドルウェアを作成する
• データの検証とシリアライズを実装する
• API のバージョン管理と後方互換性を確保する
• API エンドポイントの単体テストと統合テストを作成する

フェーズ 4：API ドキュメントと開発者エクスペリエンス

使用する場面：包括的な API ドキュメントと開発者向けリソースを作成するとき

使用するツール：

/sc:implement api-documentation
Documentation Expert: API docs and developer portal creation
API Architect: API specification validation and examples
Integration Specialist: integration guides and SDKs

作業内容：

• OpenAPI/Swagger 仕様を生成する
• 対話型の API ドキュメントとテストインターフェースを作成する
• SDK とクライアントライブラリを開発する
• 統合ガイドとコード例を作成する
• 開発者ポータルとオンボーディング資料を作成する

フェーズ 5：API ゲートウェイと統合のセットアップ

使用する場面：API ゲートウェイ、ミドルウェア、統合をセットアップするとき

使用するツール：

/sc:implement api-gateway
Integration Specialist: API gateway configuration and middleware
API Security Specialist: security policies and access control
Performance Engineer: caching, rate limiting, and optimization

作業内容：

• ルーティングとポリシーを設定して API ゲートウェイを構成する
• 認証、レート制限、ロギングのためのミドルウェアを実装する
• API の合成とオーケストレーションをセットアップする
• キャッシュとパフォーマンス最適化を構成する
• API の監視と分析を実装する

フェーズ 6：API テストと品質保証

使用する場面：API の信頼性、パフォーマンス、セキュリティを確保するとき

使用するツール：

/sc:test api-comprehensive
Performance Engineer: load testing and performance validation
API Security Specialist: security testing and vulnerability assessment
Documentation Expert: documentation accuracy and usability testing

作業内容：

• 包括的な API テストスイート（単体、統合、E2E）を実装する
• 負荷テストとパフォーマンスベンチマークを実施する
• セキュリティテストと脆弱性評価を行う
• API コントラクトとドキュメントの正確性を検証する
• エラーシナリオと復旧メカニズムをテストする

統合パターン

SuperClaude コマンドの統合

コマンド	使用例	出力
/sc:design --type api	API 設計	完全な API アーキテクチャ
/sc:implement restful	REST API	本番環境に対応した REST エンドポイント
/sc:implement graphql	GraphQL API	GraphQL スキーマとリゾルバー
/sc:implement gateway	API ゲートウェイ	構成済みの API ゲートウェイ
/sc:test api	API テスト	包括的なテストスイート

API プロトコルの統合

プロトコル	役割	機能
RESTful	標準 API	適切なセマンティクスを備えた HTTP ベースの REST API
GraphQL	柔軟な API	柔軟なクエリ言語と型システム
gRPC	高性能 API	高性能なシナリオ向けのバイナリプロトコル
WebSocket	リアルタイム API	リアルタイムの双方向通信

MCP サーバーの統合

サーバー	専門分野	使用例
Sequential	API の推論	複雑な API 設計と問題解決
Web Search	API パターン	最新の API 設計トレンドとベストプラクティス
Firecrawl	API テスト	外部 API の統合とテスト

使用例

例 1：REST API の包括的な開発

User: "Create a complete REST API for an e-commerce platform with user management, products, and orders"

Workflow:
1. Phase 1: Analyze e-commerce API requirements and design constraints
2. Phase 2: Design RESTful API architecture with proper resource modeling
3. Phase 3: Implement API endpoints with authentication and validation
4. Phase 4: Generate comprehensive API documentation and developer portal
5. Phase 5: Set up API gateway with rate limiting and monitoring
6. Phase 6: Test API performance, security, and documentation accuracy

Output: Production-ready e-commerce API with complete documentation and monitoring

例 2：GraphQL API の実装

User: "Implement a GraphQL API for a social media platform with real-time features"

Workflow:
1. Phase 1: Analyze GraphQL requirements and schema design needs
2. Phase 2: Design GraphQL schema with types, queries, and mutations
3. Phase 3: Implement resolvers with proper data fetching and caching
4. Phase 4: Create GraphQL documentation with schema explorer
5. Phase 5: Set up GraphQL gateway with subscriptions and real-time features
6. Phase 6: Test GraphQL queries, mutations, and subscription performance

Output: Feature-rich GraphQL API with real-time capabilities and comprehensive documentation

例 3：API ゲートウェイと統合

User: "Set up an API gateway to integrate multiple microservices with proper security and monitoring"

Workflow:
1. Phase 1: Analyze integration requirements and service dependencies
2. Phase 2: Design API gateway architecture with routing and policies
3. Phase 3: Implement gateway with authentication, rate limiting, and logging
4. Phase 4: Configure service discovery and load balancing
5. Phase 5: Set up monitoring, analytics, and alerting
6. Phase 6: Test gateway performance, security, and failover mechanisms

Output: Enterprise-grade API gateway with comprehensive security and monitoring

品質保証メカニズム

多層 API 検証

• 設計検証：API アーキテクチャとコントラクトの検証
• 実装テスト：包括的なエンドポイントテストと統合テスト
• ドキュメントの正確性：ドキュメントの検証と開発者からのフィードバック
• パフォーマンステスト：負荷テストとパフォーマンスベンチマーク

自動品質チェック

• コントラクトテスト：API コントラクトの自動検証と適合性確認
• セキュリティテスト：自動脆弱性スキャンとセキュリティ評価
• パフォーマンス監視：リアルタイムのパフォーマンス追跡とアラート
• ドキュメントテスト：ドキュメントの正確性と完全性の自動チェック

継続的な API 改善

• 利用状況分析：API の利用状況を追跡し、最適化を提案します
• 開発者からのフィードバック：開発者エクスペリエンスを監視し、改善します
• パフォーマンスの最適化：パフォーマンスを継続的に監視し、最適化します
• セキュリティ監視：継続的なセキュリティ評価と脅威対策を行います

成果物

主な成果物：完全な API システム

api-system/
├── endpoints/
│   ├── controllers/              # API endpoint implementations
│   ├── middleware/               # Authentication, validation, error handling
│   ├── routes/                   # API routing and endpoint definitions
│   └── validators/               # Request/response validation
├── schemas/
│   ├── openapi/                  # OpenAPI/Swagger specifications
│   ├── graphql/                  # GraphQL schemas and resolvers
│   ├── models/                   # Data models and DTOs
│   └── contracts/                # API contracts and interfaces
├── documentation/
│   ├── api-docs/                 # Interactive API documentation
│   ├── developer-portal/          # Developer portal and guides
│   ├── examples/                 # Code examples and tutorials
│   └── sdks/                     # Client libraries and SDKs
├── gateway/
│   ├── config/                   # API gateway configuration
│   ├── policies/                 # Gateway policies and rules
│   ├── middleware/               # Custom gateway middleware
│   └── monitoring/               # Gateway monitoring and analytics
├── tests/
│   ├── unit/                     # Unit tests for API endpoints
│   ├── integration/              # Integration tests for API interactions
│   ├── contract/                 # API contract tests
│   └── performance/              # Load and performance tests
└── config/
    ├── development/              # Development environment configuration
    ├── staging/                  # Staging environment configuration
    └── production/               # Production environment configuration

関連成果物

• API 仕様：完全な OpenAPI/Swagger および GraphQL スキーマ
• ドキュメントポータル：インタラクティブな API ドキュメントと開発者向けガイド
• SDK とクライアント：複数のプログラミング言語に対応したクライアントライブラリ
• 統合ガイド：段階的な統合手順と使用例
• パフォーマンスレポート：API のパフォーマンスベンチマークと最適化の推奨事項

高度な機能

インテリジェントな API 設計

• AI を活用した API 設計の推奨と最適化
• API コントラクトの自動生成と検証
• インテリジェントなエンドポイントのグループ化と整理
• API のバージョン管理と移行戦略の自動化

高度な API ゲートウェイ

• 高度なルーティングによるサービスメッシュとの統合
• AI 主導の API の構成とオーケストレーション
• 動的なポリシーの適用と適応
• リアルタイムの API 分析と最適化

開発者エクスペリエンスの向上

• インタラクティブな API のテストと探索
• 複数の言語に対応した SDK の自動生成
• リアルタイムのコラボレーションと API 設計ツール
• 充実したオンボーディングと学習リソース

API の分析とインテリジェンス

• 高度な利用状況分析とインサイト
• パフォーマンスの予測と最適化
• 異常の検知とアラート
• ビジネスインテリジェンスとの統合

トラブルシューティング

API 開発でよくある課題

• 設計上の問題：適切な API 設計パターンとアーキテクチャの原則を使用します
• 統合の問題：明確なコントラクトと適切なエラー処理を実装します
• パフォーマンスのボトルネック：クエリを最適化し、キャッシュを実装して、適切なインデックスを使用します
• ドキュメントの不足：ドキュメント生成を自動化し、定期的に更新します

API ゲートウェイと統合に関する問題

• ルーティングの問題：適切なゲートウェイ設定とサービスディスカバリーを使用します
• セキュリティの問題：包括的な認証と認可を実装します
• パフォーマンスの問題：ゲートウェイ設定を最適化し、適切なキャッシュを実装します
• 監視の不足：包括的なロギング、監視、アラートを実装します

ベストプラクティス

API 設計

• REST の原則または GraphQL のベストプラクティスに従います
• スケーラビリティと保守性を考慮して設計します
• 適切な HTTP ステータスコードとエラー処理を使用します
• 適切なバージョン管理と後方互換性を実装します

API の実装

• 適切な認証および認可の仕組みを使用します
• 包括的な入力検証とサニタイズを実装します
• 適切なエラー処理とロギングを使用します
• 充実したテストとドキュメントを作成します

API ドキュメント

• REST API には OpenAPI/Swagger を使用します
• 使用例を含むインタラクティブなドキュメントを作成します
• 明確な統合ガイドと SDK を提供します
• ドキュメントを最新かつ正確な状態に保ちます

API ゲートウェイの設定

• 適切なセキュリティポリシーとレート制限を実装します
• 包括的なロギングと監視を使用します
• 適切なロードバランシングとフェイルオーバーを設定します
• キャッシュと最適化の戦略を実装します

---

この API ビルダースキルにより、複雑な API 開発プロセスが、専門家の支援を受けながら進められるワークフローに変わります。包括的な統合機能と監視機能を備え、適切に設計・文書化された本番環境対応の API を実現します。