REST API design conventions and best practices. Use when designing endpoints, naming resources, choosing HTTP methods, structuring responses, handling errors, or planning API versioning.
# Plural nouns for collections
GET /users
GET /users/{id}
POST /users
# Nested resources for relationships
GET /users/{id}/posts
POST /users/{id}/posts
# Flat when relationship is weak or queryable
GET /posts?author={userId}
Naming Rules
Plural nouns: /users not /user
Lowercase with hyphens: /order-items not /orderItems
No verbs in paths: /users/{id}/activate → POST /users/{id}/activation
No trailing slashes: /users not /users/
Max 3 levels deep: /users/{id}/posts not /users/{id}/posts/{id}/comments/{id}/likes
HTTP Methods
相关技能
Method
Use
Idempotent
Body
GET
Read resource(s)
Yes
No
POST
Create resource
No
Yes
PUT
Replace resource entirely
Yes
Yes
PATCH
Partial update
Yes*
Yes
DELETE
Remove resource
Yes
No
*PATCH is idempotent if applying same patch yields same result.
Method Selection
Create new resource → POST /resources
Get single resource → GET /resources/{id}
Get collection → GET /resources
Replace entire resource → PUT /resources/{id}
Update specific fields → PATCH /resources/{id}
Delete resource → DELETE /resources/{id}
Trigger action → POST /resources/{id}/actions/{action}
# Filtering
GET /posts?status=published&authorId=123
# Multiple values
GET /posts?status=draft,published
# Sorting
GET /posts?sort=createdAt:desc
GET /posts?sort=title:asc,createdAt:desc
# Date ranges
GET /posts?createdAfter=2024-01-01&createdBefore=2024-12-31
# Search
GET /posts?q=typescript