rest-conventions

Original：🇺🇸 English
Translated

Use when designing API endpoints. Use when using wrong HTTP methods. Use when POST is used for reads.

1installs
Sourceyanko-belov/code-craft
Added on

NPX Install

npx skill4agent add yanko-belov/code-craft rest-conventions

Tags

Translated version includes tags in frontmatter
rest-api-designhttp-method-semanticsendpoint-designapi-best-practicesrest-conventions

SKILL.md Content

View Translation Comparison →

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:
typescript
// ❌ 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

typescript
// ✅ 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

MethodUse ForIdempotentSafe
GETRead/fetchYesYes
POSTCreateNoNo
PUTReplace entirelyYesNo
PATCHPartial updateYesNo
DELETERemoveYesNo
Safe: Doesn't modify state Idempotent: Same result if called multiple times

Common Patterns

Filtering

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

Pagination

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

Sorting

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

Actions on Resources

For actions that don't fit CRUD, use sub-resources:
typescript
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

BadGood
POST /getOrders
GET /orders
POST /createUser
POST /users
GET /deleteUser/123
DELETE /users/123
POST /updateProduct
PATCH /products/:id
POST /fetchByFilter
GET /items?filter=x

Common Rationalizations (All Invalid)

ExcuseReality
"POST is simpler"Same code, better semantics.
"Need request body"Use query parameters.
"GET URLs too long"Paginate or use search endpoint.
"That's how we do it"New code should be correct.
"Doesn't matter"Caching, bookmarking, tools all depend on it.

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