If you treat URLs like nouns then HTTP methods are the verbs that tell the server what drama to perform. Learn them and your APIs will behave. Ignore them and you will get vague bugs that only appear at 3 a m while everyone sleeps and blames caching.
Quick reference to common HTTP methods
Below are the usual suspects. Short, factual, and mildly opinionated.
- GET Retrieves a resource without changing server state. Good for fetching lists and single items.
- POST Creates a new resource or performs an action with side effects. Use this when data is being added.
- PUT Replaces a resource or creates it if it does not exist. Think of this as full replacement.
- PATCH Applies a partial update to a resource. Use this when you only change a few fields.
- DELETE Removes a resource. Yes it actually deletes things, so be kind to your database.
- HEAD Same as GET but without the response body. Useful for metadata checks and link health tests.
- OPTIONS Asks the server which methods are allowed on a URL. Often involved in CORS choreography.
- TRACE Echoes back the request for diagnostics. Mostly disabled because surprises are rarely fun in security.
Examples you can copy and paste into your brain
GET /users // fetch users
POST /users // create a new user
PUT /users/123 // replace user 123
PATCH /users/123 // update some fields for user 123
DELETE /users/123 // remove user 123
HEAD /users/123 // fetch headers for user 123 without body
OPTIONS /users // check allowed methods
Safe methods and idempotence explained without magic words
Some verbs are polite and do not change anything. These are called safe methods. GET and HEAD are safe. You can repeat them all day and your database will not file a complaint.
Idempotence means repeating the same request leaves the server in the same state as doing it once. PUT and DELETE are idempotent in the usual sense. POST usually is not idempotent. PATCH depends on the patch design so do not assume safety without thinking.
Status codes and the verbs that get along with them
Methods and status codes should be friends. When a POST successfully creates something return 201 and include a Location header or the resource in the body. When an action succeeds and there is nothing useful to return use 204 to avoid wasting bytes and everyone s time.
Practical rules to avoid angry emails
- If a request creates a resource use POST.
- If a request fully replaces a resource use PUT.
- If a request tweaks a few fields use PATCH.
- If a request just reads data use GET or HEAD.
- Prefer semantic verbs over transport level tricks. That is, use the right HTTP method instead of hiding semantics in query strings or headers.
Tip think about two things before you pick a verb. Does the request change server state and will repeating the request cause extra effects. Answering those two questions will save hours of debugging and a modest amount of workplace drama.
Pick the right verb and your clients, caches, and human teammates will thank you. Pick the wrong verb and you will remember this article fondly when you are on call at midnight.