rest-conventions（休息约定）

REST Conventions

Overview

Use HTTP methods correctly. GET for reads. POST for creates. PUT/PATCH for updates. DELETE for deletes.

REST conventions exist for caching, bookmarking, and semantic clarity. Violating them breaks HTTP infrastructure.

When to Use

• Designing any HTTP API endpoint
• Asked to use POST for fetching data
• Naming endpoints with verbs
• Unsure which HTTP method to use

The Iron Rule

NEVER use POST for read operations. NEVER put verbs in URLs.

No exceptions:

• Not for "it's simpler"
• Not for "we need a body"
• Not for "that's how we do it"
• Not for "GET URLs are limited"

Detection: REST Violation Smell

If endpoints have verbs or wrong methods, STOP:

// ❌ VIOLATIONS
POST /getOrders              // POST for read
POST /users/create           // Verb in URL
GET /deleteUser?id=123       // GET for delete
POST /api/fetchProducts      // Verb + wrong method

The Correct Pattern: RESTful Endpoints

// ✅ CORRECT: RESTful design

// Collections: plural nouns
GET    /users          // List users
POST   /users          // Create user
GET    /users/:id      // Get one user
PUT    /users/:id      // Replace user
PATCH  /users/:id      // Update user partially
DELETE /users/:id      // Delete user

// Nested resources
GET    /users/:id/orders     // User's orders
POST   /users/:id/orders     // Create order for user
GET    /orders/:id           // Get specific order

// Filtering via query params
GET    /orders?status=pending&userId=123
GET    /products?category=electronics&limit=20

HTTP Methods Semantics

Safe: Doesn't modify state Idempotent: Same result if called multiple times

Common Patterns

Filtering

GET /orders?status=pending
GET /products?minPrice=10&maxPrice=100
GET /users?role=admin&active=true

Pagination

GET /orders?page=2&limit=20
GET /orders?cursor=abc123&limit=20

Sorting

GET /products?sort=price:asc
GET /users?sort=createdAt:desc

Actions on Resources

For actions that don't fit CRUD, use sub-resources:

POST /orders/:id/cancel     // Action on order
POST /users/:id/verify      // Action on user
POST /payments/:id/refund   // Action on payment

Pressure Resistance Protocol

1. "POST Is Simpler"

Pressure: "Just use POST for everything"

Response: POST requests aren't cacheable and break HTTP semantics.

Action: Use the correct method. It's the same amount of code.

2. "We Need a Request Body"

Pressure: "GET can't have a body, so we use POST"

Response: Use query parameters for filtering. Bodies on GET are non-standard.

Action: GET /orders?userId=123 instead of POST /getOrders

3. "GET URLs Are Limited"

Pressure: "Query string might get too long"

Response: If your query is that complex, you might need a search endpoint. Or paginate.

Action: For complex searches, POST /search is acceptable as an exception.

4. "That's How We Do It"

Pressure: "Our existing API uses POST for reads"

Response: New endpoints should follow conventions. Migrate old ones gradually.

Action: Follow REST for new endpoints. Document inconsistencies.

Red Flags - STOP and Reconsider

• Verbs in URLs (/getUser, /createOrder)
• POST for fetching data
• GET for mutations
• Action names instead of resources
• Inconsistent URL structure

All of these mean: Redesign the endpoint.

Quick Reference

Common Rationalizations (All Invalid)

The Bottom Line

Nouns in URLs. Correct HTTP methods. Query params for filtering.

GET reads. POST creates. PUT/PATCH updates. DELETE removes. URLs are nouns (resources), not verbs (actions).