REST

Resource Naming

URLs identify resources — they should be nouns, not verbs. Use plural forms for collections.

# Good:
GET    /api/v1/users
POST   /api/v1/users
GET    /api/v1/users/{id}
PUT    /api/v1/users/{id}
DELETE /api/v1/users/{id}

GET    /api/v1/users/{id}/orders
POST   /api/v1/users/{id}/orders

# Avoid — verbs in URLs:
GET    /api/v1/getUsers
POST   /api/v1/createUser
GET    /api/v1/user_details/{id}

Casing

Use kebab-case for multi-word path segments:

# Good:
/api/v1/order-items
/api/v1/payment-methods

# Avoid:
/api/v1/orderItems
/api/v1/order_items

Query parameter names use camelCase:

/api/v1/users?pageSize=20&sortOrder=asc

Versioning

Version at the path root:

/api/v1/users
/api/v2/users

HTTP Methods

Method	Purpose	Idempotent
GET	Retrieve	Yes (safe)
POST	Create	No
PUT	Replace entire resource	Yes
PATCH	Partial update	No
DELETE	Remove	Yes

Status Codes

200 OK              Successful GET, PUT, PATCH
201 Created         Successful POST
204 No Content      Successful DELETE

400 Bad Request     Invalid request data
401 Unauthorized    Authentication required
403 Forbidden       Authenticated but not permitted
404 Not Found       Resource doesn't exist
409 Conflict        Duplicate or conflicting state
422 Unprocessable   Valid syntax, semantic error

500 Internal Server Error
502 Bad Gateway
503 Service Unavailable