AgentSkillsCN

API Design

API 设计

SKILL.md
--- frontmatter
name: "API Design"
id: "api-design"
version: "1.0"
claude_subagent: "api-designer"
fallback: "self-check"
min_tad_version: "2.1"
platforms: ["claude", "codex", "gemini"]

API Design Skill

Purpose

Review API endpoints for RESTful design, consistency, usability, documentation, and developer experience.

When to Use

  • •During Gate 2 (design review)
  • •When creating new API endpoints
  • •For API refactoring
  • •For GraphQL schema design
  • •For API versioning decisions

Checklist

Critical (P0) - Must Pass

  • • Consistent naming conventions (kebab-case, plural resources)
  • • Appropriate HTTP methods (GET, POST, PUT, DELETE, PATCH)
  • • Meaningful HTTP status codes
  • • Error responses follow standard format
  • • Authentication/authorization documented

Important (P1) - Should Pass

  • • Request/response schemas documented
  • • Pagination implemented for list endpoints
  • • Filtering/sorting supported where useful
  • • Rate limiting documented
  • • Versioning strategy clear

Nice-to-have (P2) - Informational

  • • OpenAPI/Swagger specification
  • • Example requests/responses provided
  • • SDK/client library considerations
  • • Webhooks for event notifications
  • • HATEOAS links where applicable

Suggestions (P3) - Optional

  • • GraphQL alternative considered
  • • Batch operations for efficiency
  • • Caching headers documented
  • • Deprecation strategy planned

Pass Criteria

LevelRequirement
P0All items pass
P1Max 2 failures
P2Informational
P3Optional

Evidence Output

Path: .tad/evidence/reviews/{date}-api-design-{task}.md

Execution Contract

  • •Input: file_paths[], api_spec{}, context{}
  • •Output: {passed: bool, findings: [{severity, endpoint, method, description, recommendation}], evidence_path: string}
  • •Timeout: 180s
  • •Parallelizable: true

Claude Enhancement

When running on Claude Code, call subagent api-designer for deeper analysis. Reference: .tad/templates/output-formats/api-review-format.md

API Design Categories

REST Conventions

  • •Resource naming (nouns, plural)
  • •HTTP method semantics
  • •URL structure hierarchy
  • •Query parameters vs path params
  • •Request body conventions

Response Design

  • •Status code accuracy
  • •Error response structure
  • •Envelope vs direct response
  • •Pagination metadata
  • •HATEOAS links

Security

  • •Authentication methods
  • •Authorization scopes
  • •Input validation
  • •Rate limiting
  • •CORS configuration

Documentation

  • •OpenAPI specification
  • •Example requests
  • •Error code reference
  • •Change log
  • •Migration guides

Developer Experience

  • •Consistent patterns
  • •Predictable behavior
  • •Clear error messages
  • •SDK-friendly design
  • •Testing support