HTTP Methods Cheatsheet - REST/HTTP Verbs & Idempotency

The hard part of API design is rarely syntax — it's deciding whether this endpoint is PUT or PATCH, and whether retrying is safe. Grouped by method semantics, idempotency, safe attributes and status-code pairing, this table explains why POST is non-idempotent and why PUT replaces whole resources while PATCH updates a subset. Use it to pick verbs from business intent so retries and concurrent calls behave predictably.

Reference·27 commands·Last updated 2026-08-02
httpMethodsrestIdempotencyapi

Core Methods 7

GET
Get资源,安全且幂,不应有副作用
POST
Create子资源or提交处理,非幂
PUT
完整Replace资源,幂(重复request结果一致)
PATCH
部分Update资源,通常不幂(除非语义保证)
DELETE
Delete资源,幂(多次删结果一致)
HEAD
同 GET 但只返回头,用于探活/cache校验
OPTIONS
查询目标supports的通信选项,CORS 预检用

Idempotency & Safety 4

安全方法
GET、HEAD、OPTIONS(不改变Service器state)
幂等方法
GET、PUT、DELETE、HEAD、OPTIONS
非幂等
POST、PATCH(默认不保证重复request一致)
Idempotency-Key
POST 重试时用request头键避免重复Create

Status Pairing 6

GET → 200 / 304
成功or命中cache
POST → 201 / 202
Create成功or已接收async处理
PUT → 200 / 204
Replace成功,可返回新资源or空
PATCH → 200 / 204
部分Update成功
DELETE → 204 / 200
Delete成功,无内容or返回摘要
方法不允许 → 405
对只supports GET 的interface发 POST

Common Mistakes 4

用 GET 改状态
违反安全语义,爬虫/预取会误触发副作用
PUT 当 PATCH 用
PUT 需传完整资源,缺field会被清空
POST 重复提交
无幂键时重试会Create重复资源
DELETE 返回 200 带正文
更规范是 204 No Content

REST Design Conventions 6

GET /users
list资源(set)
GET /users/1
单个资源(子资源)
POST /users
Create资源
PUT /users/1
整体ReplaceUser 1
PATCH /users/1
局部UpdateUser 1
DELETE /users/1
DeleteUser 1

Tips

  • PUT sends the full resource — missing fields get cleared; use PATCH for partial updates.
  • GET/HEAD/OPTIONS are safe methods — never change server state inside them.
  • Retrying POST needs an Idempotency-Key, or you may create duplicate resources.
  • The HTTP Status Codes sheet is provided separately; use both when designing APIs.

FAQ

What is the difference between HTTP 302 and 307?

Both are temporary redirects, but 302 lets browsers rewrite POST into GET (many legacy implementations do), while 307 explicitly preserves the original method and body, so POST stays POST. 301 is permanent and typically coerces methods to GET; use 307 when you must keep POST semantics and payload.

Should I use PUT or PATCH?

PUT replaces the whole resource: the client sends the full representation and missing fields are treated as cleared, and it is idempotent so repeats give the same result. PATCH does a partial update with only changed fields but is not guaranteed idempotent. Use PATCH for incremental updates and PUT for full replacement or create.

Can a GET request carry a body?

The spec does not forbid it, but in practice it is unreliable — proxies, caches and CDNs often ignore or drop it, and GET is defined as side-effect-free and cacheable. Send complex queries via URL parameters, or switch to POST when data is large or structurally sensitive. Do not depend on a GET body.

What does idempotency mean and which HTTP methods are idempotent?

Idempotent means repeating the same request any number of times leaves the server state identical, so retries are harmless. GET, PUT, DELETE, HEAD and OPTIONS are idempotent; POST is not, so resending it creates multiple resources. Only auto-retry idempotent requests, and dedupe POST with something like an idempotency key.

Should an API return 404 or 405?

404 means the resource does not exist (wrong path or already gone); 405 means the resource exists but the method is unsupported (e.g. DELETE on a read-only resource) and should include an Allow header listing valid methods. Wrong paths give 404, wrong methods give 405; some APIs return 404 for both as a security boundary, but distinct codes ease integration.

Official References

Each command links to its official documentation below, so you can verify the latest usage and read deeper.

Maintained by LaoHand

Publicly updated on Aug 2, 2026, continuously proofread against official docs.

Contact Us

Wrong command or description? Send us corrections, business inquiries or product feedback by email.

Contact Us