HTTP Request Methods Reference

GET Retrieve a Resource

The GET method requests a representation of the specified resource. GET requests should only retrieve data and should have no other effect on the server state.

When to Use

• Fetching a web page, image, or document
• Reading data from a REST API (list items, get a single resource)
• Loading search results with query parameters
• Any read-only operation where you do not need to send a request body

Key Properties

• Safe — does not modify server resources
• Idempotent — multiple identical requests return the same result
• Cacheable — responses can be cached by browsers and CDNs
• Bookmarkable — URLs with query strings can be saved and shared
• No request body — data is sent via URL query parameters

Example Request

GET /api/users/42 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer eyJhbGci...

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "admin"
}

Common Use Cases

• GET /users — List all users
• GET /users/42 — Get user with ID 42
• GET /search?q=http+methods — Search with query string
• GET /users?page=2&limit=20 — Paginated results

POST Create a Resource / Submit Data

The POST method submits data to the server, typically causing a change in state or side effects. It is most commonly used to create new resources or submit form data.

When to Use

• Creating a new resource (new user, new blog post, new order)
• Submitting a form (contact form, login form, signup)
• Uploading a file
• Triggering a process or action on the server (send email, run report)
• When the operation is not idempotent (each call creates a new resource)

Key Properties

• Not safe — modifies server state
• Not idempotent — sending the same request twice may create duplicate resources
• Not cacheable — by default (can be overridden with explicit cache headers)
• Has request body — data is sent in the body (JSON, form data, multipart)
• Typical response — 201 Created with Location header pointing to new resource

Example Request

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGci...

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "editor"
}

Example Response

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/users/43

{
  "id": 43,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "editor",
  "createdAt": "2025-01-15T10:30:00Z"
}

Common Use Cases

• POST /users — Create a new user
• POST /auth/login — Authenticate and get a token
• POST /uploads — Upload a file
• POST /orders — Place a new order
• POST /emails/send — Trigger an email

PUT Replace a Resource Entirely

The PUT method replaces the entire target resource with the request payload. If the resource does not exist, PUT can create it. The client must send the complete representation of the resource.

When to Use

• Replacing an existing resource with a complete new version
• Creating a resource at a specific, client-determined URL
• Updating all fields of a resource at once
• When you want idempotent create-or-replace semantics

Key Properties

• Not safe — modifies server state
• Idempotent — sending the same PUT request multiple times has the same effect as sending it once
• Has request body — must contain the complete resource representation
• Full replacement — omitted fields are typically set to null or defaults

Example Request

PUT /api/users/42 HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGci...

{
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "role": "admin",
  "bio": "Senior developer"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "role": "admin",
  "bio": "Senior developer",
  "updatedAt": "2025-01-15T11:00:00Z"
}

Common Use Cases

• PUT /users/42 — Replace user 42 entirely
• PUT /settings — Replace all settings at once
• PUT /documents/readme.md — Create or replace a document at a known path

PATCH Partially Update a Resource

The PATCH method applies partial modifications to a resource. Unlike PUT, you only send the fields that need to change, not the complete resource representation.

When to Use

• Updating one or a few fields of a resource without affecting others
• Toggling a single property (e.g., marking an item as read, archiving a record)
• When the resource is large and sending the full representation is wasteful
• When you want to express a delta or diff rather than a full replacement

Key Properties

• Not safe — modifies server state
• Idempotent — in practice, most PATCH implementations are idempotent (though the spec does not require it)
• Has request body — contains only the fields to update
• Partial update — fields not included in the body are left unchanged

Example Request

PATCH /api/users/42 HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGci...

{
  "role": "admin"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "admin",
  "updatedAt": "2025-01-15T11:15:00Z"
}

Common Use Cases

• PATCH /users/42 — Update specific fields of user 42
• PATCH /articles/7 with {"published": true} — Publish an article
• PATCH /notifications/99 with {"read": true} — Mark notification as read

DELETE Delete a Resource

The DELETE method removes the specified resource from the server. After a successful deletion, subsequent GET requests for the same resource should return 404 Not Found or 410 Gone.

When to Use

• Removing a resource permanently (deleting a user account, removing a file)
• Revoking access (deleting a session or API token)
• Cleaning up expired or obsolete data

Key Properties

• Not safe — modifies server state
• Idempotent — deleting the same resource multiple times has the same end result (the resource is gone)
• Typically no request body — the resource is identified by the URL
• Common responses — 200 OK (with body), 204 No Content (without body), or 202 Accepted (async)

Example Request

DELETE /api/users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGci...

Example Response

HTTP/1.1 204 No Content

Common Use Cases

• DELETE /users/42 — Delete user 42
• DELETE /sessions/current — Log out (destroy session)
• DELETE /cart/items/5 — Remove item from shopping cart
• DELETE /tokens/abc123 — Revoke an API token

HEAD Get Headers Only

The HEAD method is identical to GET except that the server does not return a response body. It is useful for checking what a GET request will return before actually downloading the resource.

When to Use

• Checking if a resource exists (without downloading it)
• Checking the Content-Length before downloading a large file
• Checking the Last-Modified or ETag headers for cache validation
• Testing if a URL is accessible (link checking, health checks)

Key Properties

• Safe — does not modify server resources
• Idempotent — same result every time
• No response body — only headers are returned
• Same headers as GET — Content-Type, Content-Length, etc. are identical

Example Request

HEAD /downloads/report.pdf HTTP/1.1
Host: files.example.com

Example Response

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 2458932
Last-Modified: Mon, 13 Jan 2025 08:00:00 GMT
ETag: "a1b2c3d4"

Common Use Cases

• Check file size before downloading: HEAD /files/backup.tar.gz
• Link validation in SEO crawlers and monitoring tools
• Conditional requests using If-None-Match or If-Modified-Since

OPTIONS Describe Communication Options

The OPTIONS method describes the communication options for the target resource. It is most commonly seen as a CORS preflight request sent by browsers before cross-origin requests.

When to Use

• CORS preflight — browsers automatically send OPTIONS before cross-origin requests with custom headers or non-simple methods
• Discovering which HTTP methods a server endpoint supports
• Checking server capabilities before making a request

Key Properties

• Safe — does not modify server resources
• Idempotent — same result every time
• Returns Allow header — lists the HTTP methods the resource supports
• CORS headers — Access-Control-Allow-Methods, Access-Control-Allow-Headers, etc.

Example Request (CORS Preflight)

OPTIONS /api/users HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type, Authorization

Example Response

HTTP/1.1 204 No Content
Allow: GET, POST, OPTIONS
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400

Common Use Cases

• Browser CORS preflight checks (automatic, not manually triggered)
• API discovery: OPTIONS /api/users — see supported methods
• Server capability detection in automated tools

TRACE Loop-Back Diagnostic

The TRACE method performs a loop-back test along the path to the target resource. The server echoes the received request back in the response body, which is useful for diagnosing issues with proxies and intermediaries.

When to Use

• Debugging proxy chains to see what headers were added or modified
• Diagnosing network path issues between client and server
• Testing whether intermediaries are altering requests

Key Properties

• Safe — does not modify server resources
• Idempotent — same result every time
• No request body — the request itself is the content of interest
• Security risk — usually disabled on production servers due to Cross-Site Tracing (XST) attacks

Example Request

TRACE /api/users HTTP/1.1
Host: api.example.com

Example Response

HTTP/1.1 200 OK
Content-Type: message/http

TRACE /api/users HTTP/1.1
Host: api.example.com
X-Forwarded-For: 203.0.113.50
Via: 1.1 proxy.example.com

CONNECT Establish a Tunnel

The CONNECT method establishes a tunnel to the server identified by the target resource. It is primarily used by HTTP proxies to create an encrypted (HTTPS) tunnel through which the client and destination server communicate directly.

When to Use

• Proxying HTTPS traffic through an HTTP proxy
• Establishing TLS/SSL tunnels
• WebSocket connections through proxies

Key Properties

• Not safe — establishes a persistent connection that could be used for any purpose
• Not idempotent — each call establishes a new tunnel
• Used by proxies — you rarely send CONNECT requests directly from application code
• Bidirectional — once established, data flows in both directions

Example Request

CONNECT www.example.com:443 HTTP/1.1
Host: www.example.com:443
Proxy-Authorization: Basic dXNlcjpwYXNz

Example Response

HTTP/1.1 200 Connection Established

(TLS handshake begins, then encrypted traffic flows through the tunnel)

PUT /api/users/42
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "admin",
  "bio": "Senior developer"
}
// You MUST include all fields, even those not changing

PATCH /api/users/42
{
  "role": "admin"
}
// Only send the field that changed