HTTP Methods

HTTP - Methods

HTTP defines a set of request methods to indicate the desired action to be performed for a given resource. These method names are case-sensitive and MUST be used in uppercase. While the set of common methods is well-defined, it can be extended. Each method has specific semantics, including properties like safety and idempotency.

Safety: Safe methods are HTTP methods that do not alter the state of the server. Essentially, they are intended for read-only operations. GET, HEAD, OPTIONS, and TRACE are defined as safe.

Idempotency: An idempotent method means that making multiple identical requests has the same effect as making a single request. GET, HEAD, PUT, DELETE, OPTIONS, and TRACE are idempotent. POST and PATCH are generally not idempotent.

S.N.	Method	Description & Properties
1	GET	Retrieves a representation of the target resource. Should only retrieve data and have no other effect on the server. Safe and idempotent.
2	HEAD	Same as GET, but the server MUST NOT send a message body in the response. Used to fetch headers. Safe and idempotent.
3	POST	Submits an entity to the specified resource, often causing a change in state or side effects (e.g., creating a new resource, submitting form data). Neither safe nor idempotent in general.
4	PUT	Replaces all current representations of the target resource with the request payload. If the resource doesn’t exist, PUT may create it. Not safe, but idempotent.
5	DELETE	Removes the specified resource. Not safe, but idempotent.
6	PATCH	Applies partial modifications to a resource. Not safe, and generally not idempotent (depends on the patch semantics).
7	CONNECT	Establishes a tunnel to the server identified by the target resource. Primarily used for HTTPS tunneling through HTTP proxies. Neither safe nor idempotent.
8	OPTIONS	Describes the communication options for the target resource (e.g., allowed methods, CORS headers). Safe and idempotent.
9	TRACE	Performs a message loop-back test along the path to the target resource. Used for debugging. Safe and idempotent, but often disabled due to security concerns (XST).

GET Method

The GET method requests a representation of the specified resource. Data can be passed in the query string of the URL. GET requests should be safe and idempotent. They can be cached and bookmarked.

Client Request:

GET /products?category=electronics&page=1 HTTP/1.1
Host: api.example.com
User-Agent: MyClient/1.0
Accept: application/json

Server Response (example):

HTTP/1.1 200 OK
Date: Tue, 22 Feb 2022 10:00:00 GMT
Server: MyAPI-Server/1.2
Content-Type: application/json; charset=utf-8
Content-Length: 256
Cache-Control: max-age=60

{
  "page": 1,
  "category": "electronics",
  "items": [
    { "id": 101, "name": "Laptop" },
    { "id": 102, "name": "Keyboard" }
  ]
}

HEAD Method

The HEAD method is identical to GET, but the server must not return a message body. It’s used to retrieve metadata (headers) about a resource, such as its Content-Type, Content-Length, or Last-Modified date, without transferring the resource itself. Useful for checking if a resource exists or has been modified.

Client Request:

HEAD /documents/report.pdf HTTP/1.1
Host: www.example.com
User-Agent: MyClient/1.0

Server Response (example):

HTTP/1.1 200 OK
Date: Tue, 22 Feb 2022 10:05:00 GMT
Server: WebServerX/2.0
Content-Type: application/pdf
Content-Length: 1024567
Last-Modified: Mon, 21 Feb 2022 15:30:00 GMT

(No message body)

POST Method

The POST method is used to submit data to be processed to a specified resource. This may result in the creation of a new resource or the updating of existing resources, or other processing on the server. POST requests typically include a message body containing the data. POST is neither safe nor idempotent.

Client Request (creating a new user with JSON):

POST /api/users HTTP/1.1
Host: api.example.com
User-Agent: MyClient/1.0
Content-Type: application/json; charset=utf-8
Content-Length: 42
Accept: application/json

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

Server Response (example, indicating resource creation):

HTTP/1.1 201 Created
Date: Tue, 22 Feb 2022 10:10:00 GMT
Server: MyAPI-Server/1.2
Content-Type: application/json; charset=utf-8
Content-Length: 65
Location: /api/users/123

{
  "id": 123,
  "name": "Jane Doe",
  "email": "jane@example.com"
}

PUT Method

The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server. If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI. PUT is idempotent but not safe.

Client Request (updating or creating a specific user):

PUT /api/users/123 HTTP/1.1
Host: api.example.com
User-Agent: MyClient/1.0
Content-Type: application/json; charset=utf-8
Content-Length: 50
Accept: application/json

{
  "name": "Jane Smith",
  "email": "jane.smith@example.com"
}

Server Response (example, 200 OK if updated, 201 Created if new, 204 No Content if updated and no body returned):

HTTP/1.1 200 OK
Date: Tue, 22 Feb 2022 10:15:00 GMT
Server: MyAPI-Server/1.2
Content-Type: application/json; charset=utf-8
Content-Length: 73

{
  "id": 123,
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "updatedAt": "2022-02-22T10:15:00Z"
}

DELETE Method

The DELETE method deletes the specified resource. It is idempotent (deleting a non-existent resource or a resource multiple times should result in the same state as deleting it once successfully) but not safe.

Client Request:

DELETE /api/users/123 HTTP/1.1
Host: api.example.com
User-Agent: MyClient/1.0
Authorization: Bearer <token>

Server Response (example, 200 OK or 204 No Content if successful, 202 Accepted if deletion is asynchronous):

HTTP/1.1 204 No Content
Date: Tue, 22 Feb 2022 10:20:00 GMT
Server: MyAPI-Server/1.2

(No message body)

PATCH Method

The PATCH method is used to apply partial modifications to a resource. Unlike PUT, which replaces the entire resource, PATCH only modifies the specified parts. The format of the patch document is specified by the Content-Type header (e.g., application/json-patch+json, application/merge-patch+json). PATCH is not safe and generally not idempotent (its idempotency depends on the patch document’s semantics).

Client Request (partially updating a user's email using JSON Merge Patch):

PATCH /api/users/123 HTTP/1.1
Host: api.example.com
User-Agent: MyClient/1.0
Content-Type: application/merge-patch+json
Content-Length: 32
Accept: application/json
Authorization: Bearer <token>

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

Server Response (example, 200 OK with updated resource or 204 No Content):

HTTP/1.1 200 OK
Date: Tue, 22 Feb 2022 10:25:00 GMT
Server: MyAPI-Server/1.2
Content-Type: application/json; charset=utf-8
Content-Length: 80

{
  "id": 123,
  "name": "Jane Smith",
  "email": "new.email@example.com",
  "updatedAt": "2022-02-22T10:25:00Z"
}

CONNECT Method

The CONNECT method establishes a tunnel to the server identified by the target resource (usually a hostname and port). It is primarily used to enable HTTPS communication through an HTTP proxy. Once the tunnel is established (indicated by a 200 Connection established response), the client can initiate a TLS handshake with the destination server through the proxy.

Client Request (to a proxy):

CONNECT www.secure-example.com:443 HTTP/1.1
Host: www.secure-example.com:443
User-Agent: MyBrowser/1.0
Proxy-Authorization: Basic <credentials_for_proxy_if_needed>

Proxy Server Response:

HTTP/1.1 200 Connection established
Proxy-Agent: MyProxy/1.0

(No message body. After this, encrypted TLS traffic flows through the tunnel.)

OPTIONS Method

The OPTIONS method requests information about the communication options available for the target resource or the server. The client can specify a URL or an asterisk (*) for the server-wide options. Common use cases include checking which HTTP methods are supported or for CORS (Cross-Origin Resource Sharing) preflight requests.

Client Request:

OPTIONS /api/users/123 HTTP/1.1
Host: api.example.com
User-Agent: MyClient/1.0
Access-Control-Request-Method: PATCH
Access-Control-Request-Headers: Content-Type, Authorization

Server Response (example, for CORS):

HTTP/1.1 204 No Content
Date: Tue, 22 Feb 2022 10:30:00 GMT
Server: MyAPI-Server/1.2
Allow: GET, HEAD, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Origin: https://client.example.com
Access-Control-Allow-Methods: GET, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400

(No message body for 204, or a body for 200 OK with general server options)

TRACE Method

The TRACE method performs a message loop-back test that echoes the received request back to the client. This can be used for debugging to see what changes, if any, are made to the request by intermediate proxies. Due to security concerns like Cross-Site Tracing (XST), TRACE is often disabled on production servers.

Client Request:

TRACE / HTTP/1.1
Host: www.example.com
User-Agent: MyClient/1.0
Custom-Header: TestValue

Server Response:

HTTP/1.1 200 OK
Date: Tue, 22 Feb 2022 10:35:00 GMT
Server: WebServerX/2.0
Content-Type: message/http

TRACE / HTTP/1.1
Host: www.example.com
User-Agent: MyClient/1.0
Custom-Header: TestValue
(Potentially other headers added by proxies, if any)