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