tech-gadget-manager/.agent/skills/api-patterns/rest.md

REST Principles

Resource-based API design - nouns not verbs.

Resource Naming Rules

Principles:
├── Use NOUNS, not verbs (resources, not actions)
├── Use PLURAL forms (/users not /user)
├── Use lowercase with hyphens (/user-profiles)
├── Nest for relationships (/users/123/posts)
└── Keep shallow (max 3 levels deep)

HTTP Method Selection

Method	Purpose	Idempotent?	Body?
GET	Read resource(s)	Yes	No
POST	Create new resource	No	Yes
PUT	Replace entire resource	Yes	Yes
PATCH	Partial update	No	Yes
DELETE	Remove resource	Yes	No

Status Code Selection

Situation	Code	Why
Success (read)	200	Standard success
Created	201	New resource created
No content	204	Success, nothing to return
Bad request	400	Malformed request
Unauthorized	401	Missing/invalid auth
Forbidden	403	Valid auth, no permission
Not found	404	Resource doesn't exist
Conflict	409	State conflict (duplicate)
Validation error	422	Valid syntax, invalid data
Rate limited	429	Too many requests
Server error	500	Our fault