Rest Api Design

作者 secondsky88378361314fMIT227 个星标收录于 2026年10月8日更新于 2026年10月8日仓库10天前更新

Designs RESTful APIs with proper resource naming, HTTP methods, status codes, and response formats. Use when building new APIs, establishing API conventions, or designing developer-friendly interfaces.

仅含说明Software Development

AI 生成的概览

指导 RESTful API 设计，涵盖资源命名、HTTP 方法、状态码与响应格式。

功能: 该技能提供 RESTful API 的设计约定，包括使用名词与层级结构的资源命名、HTTP 方法语义以及状态码选择。它还规定了 JSON 响应与集合格式，含分页与链接，以及用于过滤、排序、分页和字段选择的查询参数。最后给出 URL 版本化和 OpenAPI 文档等最佳实践清单。
适用场景: 适用于构建新 API、制定团队统一的 API 约定，或设计对开发者友好的接口。它面向端点、响应体和错误响应等早期设计决策，而非运行时实现。
运行要求: 无需任何工具、软件包、运行时、凭据或网络访问；仅为说明性内容，不附带脚本。

REST API Design

Design RESTful APIs with proper conventions and developer experience.

Resource Naming

# Good - nouns, plural, hierarchicalGET    /api/usersGET    /api/users/123GET    /api/users/123/ordersPOST   /api/usersPATCH  /api/users/123DELETE /api/users/123
# Bad - verbs, actions in URLGET    /api/getUsersPOST   /api/createUserPOST   /api/users/123/delete

# Good - nouns, plural, hierarchicalGET    /api/usersGET    /api/users/123GET    /api/users/123/ordersPOST   /api/usersPATCH  /api/users/123DELETE /api/users/123
# Bad - verbs, actions in URLGET    /api/getUsersPOST   /api/createUserPOST   /api/users/123/delete

HTTP Methods

Status Codes

Code	Meaning	Use For
200	OK	Successful GET, PATCH
201	Created	Successful POST
204	No Content	Successful DELETE
400	Bad Request	Validation errors
401	Unauthorized	Missing auth
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limited

Response Format

json

{  "data": {    "id": "123",    "type": "user",    "attributes": {      "name": "John",      "email": "[email protected]"    }  },  "meta": {    "requestId": "req_abc123"  }}

{  "data": {    "id": "123",    "type": "user",    "attributes": {      "name": "John",      "email": "[email protected]"    }  },  "meta": {    "requestId": "req_abc123"  }}

Collection Response

json

{  "data": [...],  "pagination": {    "page": 1,    "limit": 20,    "total": 150,    "totalPages": 8  },  "links": {    "self": "/api/users?page=1",    "next": "/api/users?page=2"  }}

{  "data": [...],  "pagination": {    "page": 1,    "limit": 20,    "total": 150,    "totalPages": 8  },  "links": {    "self": "/api/users?page=1",    "next": "/api/users?page=2"  }}

Query Parameters

GET /api/products?category=electronics    # FilteringGET /api/products?sort=-price,name        # SortingGET /api/products?page=2&limit=20         # PaginationGET /api/products?fields=id,name,price    # Field selection

GET /api/products?category=electronics    # FilteringGET /api/products?sort=-price,name        # SortingGET /api/products?page=2&limit=20         # PaginationGET /api/products?fields=id,name,price    # Field selection

Best Practices

Use nouns for resources, not verbs
Version API via URL path (/api/v1/)
Return appropriate status codes
Include pagination for collections
Document with OpenAPI/Swagger

来源与署名

来源：secondsky/claude-skills位于plugins/rest-api-design/skills/rest-api-design提交8837836

许可证： MIT

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

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

Rest Api Design

REST API Design

Resource Naming

HTTP Methods

Status Codes

Response Format

Collection Response

Query Parameters

Best Practices

来源与署名

更多来自 secondsky/claude-skills 的技能

Vulnerability Scanning

Web Performance Optimization

Web Performance Audit

Threejs

Tailwind V4 Shadcn

Technical Specification

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices