跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

api-design

Design or review REST/GraphQL APIs when endpoints or contracts change.

KbWen · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add KbWen/agentic-os --skill api-design

技能说明


name: api-design description: Design or review REST/GraphQL APIs when endpoints or contracts change.

API Design

When to Apply

  • Classification: feature, architecture-change, hotfix (if touching API endpoints)
  • Phase: /implement (design & build), /review (compliance check), /test (contract verification)
  • Trigger: Task involves creating, modifying, or deprecating API endpoints

Conventions

Customize after /app-init: Replace these generic conventions with your project's ADR decisions.

Endpoint Naming

  • Use nouns for resources, not verbs: GET /users not GET /getUsers
  • Plural resource names: /users, /orders, /products
  • Nested resources for relationships: /users/:id/orders
  • Use kebab-case for multi-word paths: /order-items

HTTP Methods

ActionMethodSuccess StatusIdempotent
ListGET200Yes
Get oneGET200Yes
CreatePOST201No
Full updatePUT200Yes
Partial updatePATCH200No
DeleteDELETE204Yes

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": {
      "field": "email",
      "constraint": "required"
    }
  }
}

Standard Error Codes

HTTP StatusWhenError Code Pattern
400Invalid inputVALIDATION_ERROR, INVALID_FORMAT
401Not authenticatedUNAUTHORIZED
403Not permittedFORBIDDEN
404Resource not foundNOT_FOUND
409Conflict (duplicate)CONFLICT, DUPLICATE
422Business rule violationUNPROCESSABLE
429Rate limitedRATE_LIMITED
500Server errorINTERNAL_ERROR

Pagination

{
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "per_page": 20,
    "has_next": true
  }
}

Versioning

  • URL path versioning: /api/v1/users
  • Breaking changes require new version
  • Deprecation: add Sunset header with date, keep old version for N months

Input Validation

  • Validate at the controller/route level BEFORE business logic
  • Return ALL validation errors at once (batch), not one at a time
  • Sanitize strings: trim whitespace, escape HTML where applicable
  • Enforce max lengths on all string fields

Checklist

During /implement:

  • Every endpoint has input validation
  • Every endpoint returns consistent error format
  • Every endpoint has proper auth check (or explicit public annotation)
  • Pagination for list endpoints
  • Rate limiting consideration (at least documented in spec)
  • No sensitive data in URL parameters (use body or headers)
  • Request/response examples in spec match implementation

During /review:

  • No N+1 query patterns in list endpoints
  • Proper HTTP status codes (not everything is 200)
  • Idempotency for PUT/DELETE
  • Error messages don't leak internal details (stack traces, SQL, paths)
  • CORS configured per ADR policy

Heading-Scoped Read Note

For phase-entry loading, read only:

  • When to Apply
  • Checklist

Load Conventions, Anti-Patterns, and References on full read or cache miss only.

Anti-Patterns

  • God endpoint: One endpoint that does everything based on query params. Split into specific endpoints.
  • Verb in URL: POST /createUser → POST /users
  • Inconsistent naming: Mixing /user and /products (singular vs plural)
  • Swallowing errors: Catching exceptions and returning 200 with { success: false }
  • Leaking internals: Returning DB column names directly as API fields without mapping
  • Missing 404: Returning empty 200 instead of 404 when resource doesn't exist
  • Unbounded lists: List endpoints without pagination or default limits

References

  • Project ADR: docs/adr/ADR-002-project-architecture.md § API Design
  • Security guardrails: .agent/rules/security_guardrails.md (A01: Access Control, A03: Injection)
  • Spec template: .agentcortex/templates/spec-app-feature.md § API Contract