Back to Details

api-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Design

API设计

Design clear, consistent, and developer-friendly REST APIs.

设计清晰、一致且对开发者友好的REST APIs。

When NOT to Use

不适用于以下场景

Consuming external APIs — Use
```
api-integration
```
for building clients to call third-party services (Stripe, Twilio, etc.)
Writing tests for APIs — Use
```
testing-strategy
```
for contract tests, integration tests, mocking strategies
Reviewing existing API security — Use
```
security-audit
```
for vulnerability scanning of live endpoints
Designing auth mechanisms that are the whole task — Use
```
security-audit
```
if reviewing, this skill if designing from scratch

调用外部API — 若要构建调用第三方服务（如Stripe、Twilio等）的客户端，请使用
```
api-integration
```
为API编写测试 — 若要进行契约测试、集成测试、模拟策略，请使用
```
testing-strategy
```
评审现有API安全性 — 若要对实时端点进行漏洞扫描，请使用
```
security-audit
```
将设计认证机制作为全部任务 — 若为评审，请使用
```
security-audit
```
；若为从零开始设计，则使用本技能

Core Principles

核心原则

Resource-oriented — Design around nouns (resources), not verbs (actions)
Predictable patterns — Consistent URL structure, response format, and behavior
Clear contracts — Explicit schemas, documented errors, versioned endpoints
Developer experience — Meaningful errors, helpful examples, logical defaults

面向资源 — 围绕名词（资源）而非动词（操作）进行设计
可预测的模式 — 一致的URL结构、响应格式和行为
清晰的契约 — 明确的模式、文档化的错误信息、带版本的端点
开发者体验 — 有意义的错误提示、实用的示例、合理的默认值

Quick Start Checklist

快速入门检查清单

Identify resources and their relationships
Define CRUD operations + custom actions with correct HTTP methods
Design request/response schemas with consistent envelope
Plan error format with status codes, error codes, and field-level details
Write OpenAPI specification with examples
Review for consistency, security, and usability

识别资源及其关系
使用正确的HTTP方法定义CRUD操作+自定义操作
设计带有统一封装结构的请求/响应模式
规划包含状态码、错误码和字段级详情的错误格式
编写带示例的OpenAPI规范
从一致性、安全性和易用性方面进行评审

Design Quick Reference

设计快速参考

Method	Purpose	Idempotent	Body
GET	Read	Yes	No
POST	Create	No	Yes
PUT	Replace	Yes	Yes
PATCH	Partial update	Yes*	Yes
DELETE	Remove	Yes	No

方法	用途	幂等性	请求体
GET	读取	是	无
POST	创建	否	有
PUT	替换	是	有
PATCH	部分更新	是*	有
DELETE	删除	是	无

References

参考资料

Reference	Description
endpoints.md	URL design, HTTP methods, resource modeling
requests-responses.md	Request/response formats, headers, content types
status-codes.md	HTTP status codes, error handling patterns
pagination-filtering.md	Pagination, filtering, sorting, searching
versioning.md	API versioning strategies
openapi.md	OpenAPI specification, documentation
security.md	Authentication, authorization, rate limiting
tdd-patterns.md	Test-first patterns for REST endpoints, supertest templates
review-checklist.md	API design review checklist (validation, auth, performance, docs)

参考文档	描述
endpoints.md	URL设计、HTTP方法、资源建模
requests-responses.md	请求/响应格式、请求头、内容类型
status-codes.md	HTTP状态码、错误处理模式
pagination-filtering.md	分页、过滤、排序、搜索
versioning.md	API版本控制策略
openapi.md	OpenAPI规范、文档
security.md	认证、授权、速率限制
tdd-patterns.md	REST端点的测试优先模式、supertest模板
review-checklist.md	API设计评审检查清单（验证、认证、性能、文档）