HTTP Methods Reference

HTTP methods define the type of action a client wants to perform on a resource. Choosing the right method is fundamental to building predictable, correct REST APIs. This reference covers all nine standard HTTP methods with their properties, use cases, and ready-to-run cURL examples.

HTTP Methods Overview

The HTTP specification defines nine methods, sometimes called “verbs.” The four most common in REST APIs are GET, POST, PUT/PATCH, and DELETE — but HEAD, OPTIONS, TRACE, and CONNECT each serve important purposes.

Safe vs. Unsafe Methods

A safe method has no side effects on the server — calling it does not change any state. GET, HEAD, OPTIONS, and TRACE are safe. POST, PUT, PATCH, DELETE, and CONNECT are unsafe.

Safe methods are important for caching: browsers and CDNs will cache GET and HEAD responses freely. They are also important for prefetching: a browser might speculatively prefetch a GET link but will never prefetch a POST.

Idempotent Methods

An idempotent method produces the same result regardless of how many times it is called. GET, HEAD, PUT, DELETE, OPTIONS, and TRACE are idempotent. POST and PATCH are typically not.

Idempotency matters for network reliability. If a DELETE request times out, you can safely retry it — the resource is either already deleted or will be deleted by the retry. If a POST request times out, retrying might create a duplicate record. APIs that need idempotent POST (e.g., payment processing) often use an Idempotency-Key header.

PUT vs. PATCH: When to Use Each

This is one of the most common sources of confusion in REST API design.

Use PUT when you are replacing the entire resource. The request body must contain the complete new state. Fields omitted from the body are cleared. PUT is idempotent: PUT /users/42 with the same body always produces the same result.

Use PATCH when you are updating only specific fields. The request body contains only the changes, not the full resource. PATCH is more efficient over the network but is not guaranteed to be idempotent (though most simple implementations are).

Example: updating a user’s email address:

• PUT: send the entire user object with the new email — all other fields must be included
• PATCH: send {"email": "new@example.com"} — only the email is changed

CORS Preflight and OPTIONS

Browsers automatically send an OPTIONS request before cross-origin POST, PUT, or DELETE requests (called a “preflight”). This checks whether the server allows the cross-origin request before making it.

Your server must respond to OPTIONS with the appropriate CORS headers:

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400

The Access-Control-Max-Age header caches the preflight response, reducing the number of extra OPTIONS requests.

Cacheable Methods

Only GET and HEAD are cacheable by default. Caching means the browser or a CDN can store the response and return it without hitting the server. This is controlled by response headers:

• Cache-Control: max-age=3600 — cache for 1 hour
• ETag: "abc123" — allows conditional requests (If-None-Match)
• Last-Modified — allows conditional requests (If-Modified-Since)

POST responses can be cached if the server explicitly includes Cache-Control or Expires headers, but this is rare.

REST API Design Conventions

Frequently Asked Questions

What is the difference between PUT and PATCH? PUT replaces the entire resource — you must send all fields. PATCH applies partial changes — you only send what changed. Use PATCH for efficiency when updating a single field; use PUT when you have the full resource state.

Why can’t POST requests be cached? POST is not idempotent, so the browser and CDN cannot assume that two identical POST requests return the same response. Caching POST would risk returning stale data for requests that are intended to have side effects.

What does “safe” mean for an HTTP method? A safe method does not modify server state. GET, HEAD, OPTIONS, and TRACE are safe. This property allows browsers to prefetch safe requests, and it allows tools like Google’s search crawler to follow GET links without triggering side effects.

When should I use DELETE vs. POST /archive? Use DELETE when you are permanently removing a resource. Use POST /archive (or a similar action URL) when you want to soft-delete or change state without permanent removal. Some teams prefer explicit action endpoints for business operations.

Why does my browser send an OPTIONS request before my API call? This is the CORS preflight check. Browsers send OPTIONS before cross-origin requests that use non-simple methods (POST, PUT, DELETE) or custom headers. Your API server must handle OPTIONS and return the appropriate Access-Control-Allow-* headers.

Is PATCH idempotent? Technically no — the HTTP spec does not require PATCH to be idempotent. But in practice, most REST APIs implement PATCH as idempotent for simple field-value updates. If your PATCH uses instructions like “increment by 1”, it is not idempotent. If it uses “set email to X”, it effectively is.