name: rest-conventions
description: Use when designing API endpoints. Use when using wrong HTTP methods. Use when POST is used for reads.

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).