AgentSkillsCN

API Design

设计RESTful API，采用恰当的资源建模、HTTP方法、错误处理与清晰合约，遵循REST原则

SKILL.md
--- frontmatter
name: "API Design"
description: "Design RESTful APIs with proper resource modeling, HTTP methods, error handling, and clear contracts following REST principles"
category: "architecture"
required_tools: ["Read", "Write", "WebSearch"]

API Design

Purpose

Design clear, consistent, and maintainable REST APIs following industry best practices and conventions.

When to Use

  • •Designing new API endpoints
  • •Refactoring existing APIs
  • •Creating integration interfaces
  • •Planning service-to-service communication

Key Capabilities

  1. •REST Principles - Apply RESTful design patterns correctly
  2. •Resource Modeling - Design clear resource hierarchies
  3. •Error Responses - Define consistent error handling

Approach

  1. •Identify resources and their relationships
  2. •Design URL structure (nouns, not verbs)
  3. •Choose appropriate HTTP methods (GET, POST, PUT, DELETE)
  4. •Design request/response formats
  5. •Plan error handling and status codes
  6. •Document with examples

Example

Context: User profile management API

Design:

code
GET    /users/{id}           # Get user
POST   /users                # Create user
PUT    /users/{id}           # Update user
DELETE /users/{id}           # Delete user
GET    /users/{id}/profile   # Get profile
PUT    /users/{id}/profile   # Update profile

Best Practices

  • •✅ Use nouns for resources, HTTP verbs for actions
  • •✅ Consistent URL patterns and naming
  • •✅ Proper HTTP status codes (200, 201, 404, 500)
  • •❌ Avoid: Verbs in URLs (/getUser, /createUser)