api-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Builder - Complete API Development Workflow

API Builder - 全流程API开发工作流

Overview

概述

This skill provides end-to-end API development services by orchestrating API architects, integration specialists, and documentation experts. It transforms API requirements into production-ready APIs with comprehensive design, documentation, testing, and integration capabilities.

Key Capabilities:

🏗️ Multi-Protocol API Design - RESTful APIs, GraphQL, gRPC, and WebSocket implementations
📚 Comprehensive Documentation - Auto-generated API docs, interactive testing, and developer guides
🔧 Integration Architecture - API gateways, middleware, and third-party service integration
📊 API Analytics & Monitoring - Usage tracking, performance monitoring, and error analysis
🛡️ API Security & Governance - Authentication, rate limiting, and API lifecycle management

该技能通过统筹API架构师、集成专家与文档专家，提供端到端的API开发服务。它能将API需求转化为具备完善设计、文档、测试与集成能力的生产级API。

核心能力：

🏗️ 多协议API设计 - 支持RESTful APIs、GraphQL、gRPC及WebSocket实现
📚 全面文档管理 - 自动生成API文档、交互式测试及开发者指南
🔧 集成架构设计 - API网关、中间件及第三方服务集成
📊 API分析与监控 - 用量追踪、性能监控及错误分析
🛡️ API安全与治理 - 身份认证、速率限制及API生命周期管理

When to Use This Skill

适用场景

Perfect for:

RESTful API design and implementation
GraphQL schema development and resolver implementation
API gateway setup and middleware configuration
API documentation generation and developer portal creation
API integration patterns and third-party service connections
API versioning and lifecycle management

Triggers:

"Design and implement a REST API for [application]"
"Create a GraphQL API with [features]"
"Set up an API gateway with [middleware]"
"Generate comprehensive API documentation"
"Implement API integration with [service]"

理想适用场景：

RESTful API设计与实现
GraphQL schema开发与解析器实现
API网关搭建与中间件配置
API文档生成与开发者门户创建
API集成模式与第三方服务对接
API版本管理与生命周期管控

触发指令：

"为[应用]设计并实现一套REST API"
"创建具备[功能]的GraphQL API"
"搭建带有[中间件]的API网关"
"生成全面的API文档"
"实现与[服务]的API集成"

API Development Expert Panel

API开发专家团队

API Architect (API Design & Architecture)

API架构师（API设计与架构）

Focus: API design patterns, protocol selection, architectural decisions
Techniques: RESTful design, GraphQL schema design, API composition
Considerations: Scalability, maintainability, developer experience, performance

专注方向：API设计模式、协议选择、架构决策
技术方法：RESTful设计、GraphQL schema设计、API组合
考量因素：可扩展性、可维护性、开发者体验、性能

Integration Specialist (API Integration & Middleware)

集成专家（API集成与中间件）

Focus: API gateways, middleware, third-party integrations
Techniques: API composition, service mesh, event-driven architecture
Considerations: Latency, reliability, security, monitoring

专注方向：API网关、中间件、第三方集成
技术方法：API组合、服务网格、事件驱动架构
考量因素：延迟、可靠性、安全性、监控

Documentation Expert (API Documentation & Developer Experience)

文档专家（API文档与开发者体验）

Focus: API documentation, developer portals, interactive testing
Techniques: OpenAPI/Swagger, GraphQL docs, API testing frameworks
Considerations: Developer experience, documentation accuracy, discoverability

专注方向：API文档、开发者门户、交互式测试
技术方法：OpenAPI/Swagger、GraphQL文档、API测试框架
考量因素：开发者体验、文档准确性、可发现性

API Security Specialist (API Security & Governance)

API安全专家（API安全与治理）

Focus: API security, authentication, authorization, governance
Techniques: OAuth 2.0, API keys, rate limiting, threat protection
Considerations: Security by design, compliance, usability

专注方向：API安全、身份认证、授权、治理
技术方法：OAuth 2.0、API密钥、速率限制、威胁防护
考量因素：设计安全、合规性、易用性

Performance Engineer (API Optimization & Monitoring)

性能工程师（API优化与监控）

Focus: API performance, caching, monitoring, analytics
Techniques: Response optimization, caching strategies, load balancing
Considerations: Response times, throughput, resource utilization

专注方向：API性能、缓存、监控、分析
技术方法：响应优化、缓存策略、负载均衡
考量因素：响应时间、吞吐量、资源利用率

API Development Workflow

API开发工作流

Phase 1: API Requirements Analysis & Design Planning

阶段1：API需求分析与设计规划

Use when: Starting API development or API modernization

Tools Used:

bash

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

Activities:

Analyze business requirements and translate to API specifications
Identify API protocols and architectural patterns
Define API contracts and data models
Plan integration points and external dependencies
Establish API governance and versioning strategy

适用场景：启动API开发或API现代化改造

使用工具：

bash

/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治理与版本化策略

Phase 2: API Architecture & Protocol Design

阶段2：API架构与协议设计

Use when: Designing the API structure and choosing protocols

Tools Used:

bash

/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

Activities:

Design API architecture and protocol selection (REST/GraphQL/gRPC)
Create API specifications and data contracts
Design endpoint structures and resource relationships
Plan API composition and orchestration patterns
Define error handling and response formats

适用场景：设计API结构与选择协议

使用工具：

bash

/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组合与编排模式
定义错误处理与响应格式

Phase 3: API Implementation & Development

阶段3：API实现与开发

Use when: Writing the actual API code and business logic

Tools Used:

bash

/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

Activities:

Implement API endpoints and business logic
Create middleware for authentication, validation, and error handling
Implement data validation and serialization
Create API versioning and backward compatibility
Write unit and integration tests for API endpoints

适用场景：编写实际API代码与业务逻辑

使用工具：

bash

/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端点编写单元测试与集成测试

Phase 4: API Documentation & Developer Experience

阶段4：API文档与开发者体验

Use when: Creating comprehensive API documentation and developer resources

Tools Used:

bash

/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

Activities:

Generate OpenAPI/Swagger specifications
Create interactive API documentation and testing interfaces
Develop SDKs and client libraries
Write integration guides and code examples
Create developer portal and onboarding materials

适用场景：创建全面的API文档与开发者资源

使用工具：

bash

/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与客户端库
编写集成指南与代码示例
创建开发者门户与入门材料

Phase 5: API Gateway & Integration Setup

阶段5：API网关与集成搭建

Use when: Setting up API gateway, middleware, and integrations

Tools Used:

bash

/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

Activities:

Configure API gateway with routing and policies
Implement middleware for authentication, rate limiting, and logging
Set up API composition and orchestration
Configure caching and performance optimization
Implement API monitoring and analytics

适用场景：搭建API网关、中间件与集成

使用工具：

bash

/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监控与分析

Phase 6: API Testing & Quality Assurance

阶段6：API测试与质量保障

Use when: Ensuring API reliability, performance, and security

Tools Used:

bash

/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

Activities:

Implement comprehensive API test suites (unit, integration, E2E)
Conduct load testing and performance benchmarking
Perform security testing and vulnerability assessment
Validate API contracts and documentation accuracy
Test error scenarios and recovery mechanisms

适用场景：确保API可靠性、性能与安全性

使用工具：

bash

/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测试套件（单元、集成、端到端）
开展负载测试与性能基准测试
执行安全测试与漏洞评估
验证API契约与文档准确性
测试错误场景与恢复机制

Integration Patterns

集成模式

SuperClaude Command Integration

SuperClaude命令集成

Command	Use Case	Output
`/sc:design --type api`	API design	Complete API architecture
`/sc:implement restful`	REST API	Production-ready REST endpoints
`/sc:implement graphql`	GraphQL API	GraphQL schema and resolvers
`/sc:implement gateway`	API gateway	Configured API gateway
`/sc:test api`	API testing	Comprehensive test suite

命令	适用场景	输出
`/sc:design --type api`	API设计	完整API架构
`/sc:implement restful`	REST API	生产级REST端点
`/sc:implement graphql`	GraphQL API	GraphQL schema与解析器
`/sc:implement gateway`	API网关	已配置的API网关
`/sc:test api`	API测试	全面测试套件

API Protocol Integration

API协议集成

Protocol	Role	Capabilities
RESTful	Standard API	HTTP-based REST API with proper semantics
GraphQL	Flexible API	Flexible query language and type system
gRPC	High-performance API	Binary protocol for high-performance scenarios
WebSocket	Real-time API	Real-time bidirectional communication

协议	定位	能力
RESTful	标准API	基于HTTP的REST API，具备规范语义
GraphQL	灵活API	灵活的查询语言与类型系统
gRPC	高性能API	适用于高性能场景的二进制协议
WebSocket	实时API	实时双向通信

MCP Server Integration

MCP Server集成

Server	Expertise	Use Case
Sequential	API reasoning	Complex API design and problem-solving
Web Search	API patterns	Latest API design trends and best practices
Firecrawl	API testing	External API integration and testing

服务器	专长	适用场景
Sequential	API推理	复杂API设计与问题解决
Web Search	API模式	最新API设计趋势与最佳实践
Firecrawl	API测试	外部API集成与测试

Usage Examples

使用示例

Example 1: Complete REST API Development

示例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

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

Example 2: GraphQL API Implementation

示例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

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

Example 3: API Gateway and Integration

示例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

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

Quality Assurance Mechanisms

质量保障机制

Multi-Layer API Validation

多层API验证

Design Validation: API architecture and contract validation
Implementation Testing: Comprehensive endpoint and integration testing
Documentation Accuracy: Documentation validation and developer feedback
Performance Testing: Load testing and performance benchmarking

设计验证：API架构与契约验证
实现测试：全面的端点与集成测试
文档准确性：文档验证与开发者反馈
性能测试：负载测试与性能基准测试

Automated Quality Checks

自动化质量检查

Contract Testing: Automated API contract validation and compliance
Security Testing: Automated vulnerability scanning and security assessment
Performance Monitoring: Real-time performance tracking and alerting
Documentation Testing: Automated documentation accuracy and completeness checks

契约测试：自动化API契约验证与合规性检查
安全测试：自动化漏洞扫描与安全评估
性能监控：实时性能追踪与告警
文档测试：自动化文档准确性与完整性检查

Continuous API Improvement

持续API优化

Usage Analytics: API usage tracking and optimization recommendations
Developer Feedback: Developer experience monitoring and improvement
Performance Optimization: Continuous performance monitoring and optimization
Security Monitoring: Ongoing security assessment and threat protection

用量分析：API用量追踪与优化建议
开发者反馈：开发者体验监控与改进
性能优化：持续性能监控与优化
安全监控：持续安全评估与威胁防护

Output Deliverables

输出交付物

Primary Deliverable: Complete API System

核心交付物：完整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-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

Supporting Artifacts

辅助交付物

API Specifications: Complete OpenAPI/Swagger and GraphQL schemas
Documentation Portal: Interactive API documentation and developer guides
SDKs and Clients: Client libraries for multiple programming languages
Integration Guides: Step-by-step integration instructions and examples
Performance Reports: API performance benchmarks and optimization recommendations

API规范：完整的OpenAPI/Swagger与GraphQL schema
文档门户：交互式API文档与开发者指南
SDK与客户端：多编程语言的客户端库
集成指南：分步集成说明与示例
性能报告：API性能基准与优化建议

Advanced Features

高级功能

Intelligent API Design

智能API设计

AI-powered API design recommendations and optimization
Automatic API contract generation and validation
Intelligent endpoint grouping and organization
Automated API versioning and migration strategies

AI驱动的API设计建议与优化
自动API契约生成与验证
智能端点分组与组织
自动化API版本化与迁移策略

Advanced API Gateway

高级API网关

Service mesh integration with advanced routing
AI-driven API composition and orchestration
Dynamic policy enforcement and adaptation
Real-time API analytics and optimization

服务网格集成与高级路由
AI驱动的API组合与编排
动态策略执行与适配
实时API分析与优化

Developer Experience Enhancement

开发者体验增强

Interactive API testing and exploration
Automated SDK generation for multiple languages
Real-time collaboration and API design tools
Comprehensive onboarding and learning resources

交互式API测试与探索
多语言自动SDK生成
实时协作与API设计工具
全面的入门与学习资源

API Analytics and Intelligence

API分析与智能

Advanced usage analytics and insights
Performance prediction and optimization
Anomaly detection and alerting
Business intelligence integration

高级用量分析与洞察
性能预测与优化
异常检测与告警
商业智能集成

Troubleshooting

故障排除

Common API Development Challenges

常见API开发挑战

Design Issues: Use proper API design patterns and architectural principles
Integration Problems: Implement clear contracts and proper error handling
Performance Bottlenecks: Optimize queries, implement caching, and use proper indexing
Documentation Gaps: Use automated documentation generation and regular updates

设计问题：采用标准API设计模式与架构原则
集成问题：明确契约并实现完善的错误处理
性能瓶颈：优化查询、实现缓存与合理索引
文档缺口：使用自动化文档生成并定期更新

API Gateway and Integration Issues

API网关与集成问题

Routing Problems: Use proper gateway configuration and service discovery
Security Issues: Implement comprehensive authentication and authorization
Performance Issues: Optimize gateway configuration and implement proper caching
Monitoring Gaps: Implement comprehensive logging, monitoring, and alerting

路由问题：正确配置网关与服务发现
安全问题：实现全面的身份认证与授权
性能问题：优化网关配置并合理实现缓存
监控缺口：实现全面的日志、监控与告警

Best Practices

最佳实践

For API Design

API设计

Follow RESTful principles or GraphQL best practices
Design for scalability and maintainability
Use proper HTTP status codes and error handling
Implement proper versioning and backward compatibility

遵循RESTful原则或GraphQL最佳实践
为可扩展性与可维护性设计
使用标准HTTP状态码与错误处理
实现合理的版本化与向后兼容性

For API Implementation

API实现

Use proper authentication and authorization mechanisms
Implement comprehensive input validation and sanitization
Use proper error handling and logging
Write comprehensive tests and documentation

使用标准身份认证与授权机制
实现全面的输入验证与清理
使用合理的错误处理与日志
编写全面的测试与文档

For API Documentation

API文档

Use OpenAPI/Swagger for REST APIs
Create interactive documentation with examples
Provide clear integration guides and SDKs
Keep documentation updated and accurate

为REST API使用OpenAPI/Swagger
创建带有示例的交互式文档
提供清晰的集成指南与SDK
保持文档更新与准确

For API Gateway Configuration

API网关配置

Implement proper security policies and rate limiting
Use comprehensive logging and monitoring
Configure proper load balancing and failover
Implement caching and optimization strategies

This API builder skill transforms the complex process of API development into a guided, expert-supported workflow that ensures well-designed, well-documented, and production-ready APIs with comprehensive integration and monitoring capabilities.

实现合理的安全策略与速率限制
使用全面的日志与监控
配置合理的负载均衡与故障转移
实现缓存与优化策略

该API Builder技能将复杂的API开发流程转化为有指导、专家支持的工作流，确保产出设计优良、文档完善、具备全面集成与监控能力的生产级API。