HTTP Methods

The GET method requests a representation of the specified resource. GET requests should only retrieve data and have no other effect on the resource. Because GET requests do not modify state, they are considered safe and idempotent.

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

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=60

{
  "id": 123,
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "role": "admin",
  "createdAt": "2025-08-14T10:30:00Z"
}

The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server. It is commonly used to create new resources or trigger operations. POST is neither safe nor idempotent, meaning repeated identical requests may create duplicate resources.

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

{
  "name": "Bob Smith",
  "email": "bob@example.com",
  "role": "member"
}

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

{
  "id": 456,
  "name": "Bob Smith",
  "email": "bob@example.com",
  "role": "member",
  "createdAt": "2026-03-02T14:22:00Z"
}

The PUT method replaces all current representations of the target resource with the request payload. If the resource does not exist, PUT may create it. PUT is idempotent, meaning making the same request multiple times produces the same result as making it once.

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

{
  "name": "Alice Johnson-Smith",
  "email": "alice.js@example.com",
  "role": "admin"
}

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

{
  "id": 123,
  "name": "Alice Johnson-Smith",
  "email": "alice.js@example.com",
  "role": "admin",
  "updatedAt": "2026-03-02T15:10:00Z"
}

The PATCH method applies partial modifications to a resource. Unlike PUT, which replaces the entire resource, PATCH only updates the fields provided in the request body. PATCH is neither safe nor necessarily idempotent, though it can be implemented in an idempotent fashion.

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

{
  "email": "alice.new@example.com"
}

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

{
  "id": 123,
  "name": "Alice Johnson",
  "email": "alice.new@example.com",
  "role": "admin",
  "updatedAt": "2026-03-02T15:45:00Z"
}

The DELETE method removes the specified resource from the server. After a successful DELETE, subsequent GET requests to the same URI should return 404 Not Found. DELETE is idempotent, meaning deleting an already-deleted resource should not produce an error beyond the initial removal.

DELETE /api/users/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

HTTP/1.1 204 No Content
X-Request-Id: req_abc123

The HEAD method is identical to GET except that the server must not return a message body in the response. It is useful for checking if a resource exists, inspecting headers, or testing links without downloading the entire response. HEAD is safe and idempotent.

HEAD /api/users/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

The OPTIONS method describes the communication options available for the target resource. It is commonly used in CORS preflight requests where the browser checks which HTTP methods and headers are permitted before sending the actual request. OPTIONS is safe and idempotent.

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

The TRACE method performs a message loop-back test along the path to the target resource, echoing back the received request. It is primarily used for diagnostic purposes to see how intermediate proxies modify the request. TRACE is rarely used in production APIs and is often disabled for security reasons.

TRACE /api/users HTTP/1.1
Host: api.example.com
Max-Forwards: 3

The CONNECT method establishes a tunnel to the server identified by the target resource. It is primarily used with HTTP proxies to initiate an end-to-end TLS/SSL connection through the proxy, enabling HTTPS traffic to pass through an HTTP proxy. CONNECT is neither safe nor cacheable.

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