If you are reading this you probably like telling computers what to do and then watching them ignore you. Calm down, that is normal. REST is basically a polite argument between clients and servers where URLs name things and HTTP methods do the heavy lifting. Get the nouns right and the verbs will behave.

URLs are nouns and HTTP methods are verbs

Think of a URL as a noun that points to a resource. Use plural nouns for collections and hierarchical segments for relationships. That means paths like /users and /users/123/posts/456 are sensible. Avoid embedding verbs in path segments. You do not need /getUser unless you want to cause grief.

Example patterns that do not lie

GET    /users          retrieves a collection or list of users
GET    /users/123      retrieves user 123
POST   /users          creates a new user under the users collection
PUT    /users/123      replaces user 123 fully
PATCH  /users/123      applies a partial update to user 123
DELETE /users/123      removes user 123
HEAD   /users/123      checks headers without the body

GET and HEAD behave when you do not make them cry

GET is safe and cacheable when your responses allow caching. That means no naughty side effects like changing state when someone asks for data. HEAD is like GET but without the body. It is useful for checking headers, existence, or caching metadata before you waste bandwidth on a full download.

POST is the messy one and idempotency is your friend

POST creates things. It is not idempotent by default, which means retries may produce duplicates. If clients might retry requests, design your server to accept an idempotency key or token with POST requests. This saves support tickets and passive aggressive emails.

PUT replaces, PATCH edits, DELETE vanishes

PUT replaces the whole resource, so you send the full user object when you use PUT. PUT is idempotent, so repeating the same PUT leaves the resource in the same state. PATCH is for deltas. Use it when you only want to change a few fields and avoid re-sending the entire resource. DELETE typically behaves idempotently because deleting something twice still leaves it gone.

When to pick which method

• Use GET for reads and for operations that can be cached safely
• Use POST to create when the server assigns identifiers or when actions are inherently non idempotent
• Use PUT when you can send a full representation and you want idempotency
• Use PATCH for partial updates and smaller payloads
• Use DELETE to remove resources
• Use HEAD for quick existence checks or to inspect response headers

Status codes that do the talking

Return meaningful status codes so clients do not have to guess. 200 means success with a body. 201 signals a created resource. 204 is success with no body. 404 means not found. 409 hints at conflicts. Pick the right code and you will make life easier for everyone who has to integrate with your API.

Practical rules to stop accidental chaos

• Use nouns for paths and avoid verbs in path segments
• Use query parameters for filtering and paging, not for actions
• Prefer idempotent methods for operations that may be retried by clients
• Accept an idempotency key on POST for non idempotent operations that clients may retry
• Document behavior for caching, conditional requests, and error responses so nobody has to reverse engineer your intentions

In short, model your REST API around resources, pick HTTP methods that match intent, and be kind to clients by being predictable. Do that and your APIs will be less likely to ignite passive aggressive bug reports. If you slip up, fix the design rather than sending angry emails.