RFC 7231

https://www.rfc-editor.org/rfc/rfc7231.html
Admin
RFC 7231 is an IETF specification defining the semantics and content of HTTP/1.1 messages, including...
Tokens:48,691
Snippets:310
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### CONNECT server.example.com:80 HTTP/1.1

Source: https://www.rfc-editor.org/rfc/rfc7231.html

The CONNECT method establishes a tunnel to a server through a proxy. This example shows a CONNECT request with proxy authentication.

```APIDOC
## CONNECT [request-target]

### Description
The CONNECT method requests that the proxy establish a tunnel to the server identified by the request-target. It is used to create a transparent connection for protocols like TLS.

### Method
CONNECT

### Endpoint
[request-target] (e.g., server.example.com:80)

### Parameters
#### Request Headers
- **Host** (string) - Required - The host and port of the target server.
- **Proxy-Authorization** (string) - Optional - Credentials for proxy authentication.

### Request Example
```
CONNECT server.example.com:80 HTTP/1.1
Host: server.example.com:80
Proxy-Authorization: basic aGVsbG86d29ybGQ=
```

### Response
#### Success Response (2xx)
- The tunnel is established after the blank line following the response header section.
- The server MUST NOT send Transfer-Encoding or Content-Length in a 2xx response.
- The client MUST ignore any Content-Length or Transfer-Encoding in a successful response.

#### Error Response
- Any response other than 2xx indicates the tunnel has not been formed.

### Notes
- CONNECT responses are not cacheable.
- Payload in CONNECT request has no defined semantics and may cause rejection.
- Proxies SHOULD restrict CONNECT to a limited set of known ports or a whitelist.
```

--------------------------------

### HEAD

Source: https://www.rfc-editor.org/rfc/rfc7231.html

Same as GET, but only transfers the status line and header section. This method is safe and must be supported by all general-purpose servers.

```APIDOC
## HEAD

### Description
Same as GET, but only transfer the status line and header section.

### Method
HEAD

### Endpoint
[Target resource URI]

### Response
#### Success Response (200)
- **headers** (header section) - The header section of the response, without a message body.

#### Response Example
(No example provided in source.)
```

--------------------------------

### GET

Source: https://www.rfc-editor.org/rfc/rfc7231.html

The GET method requests transfer of the current selected representation for the target resource. It is safe and idempotent.

```APIDOC
## GET [target resource]

### Description
The GET method requests transfer of the current selected representation for the target resource. GET is the primary mechanism of information retrieval and should be used for read-only operations.

### Method
GET

### Endpoint
[target resource URI]

### Response
#### Success Response (200)
- **body** (representation) - The current representation of the target resource.

#### Response Example
(No explicit example provided in source.)
```

--------------------------------

### GET

Source: https://www.rfc-editor.org/rfc/rfc7231.html

Transfers a current representation of the target resource. This method is safe and must be supported by all general-purpose servers.

```APIDOC
## GET

### Description
Transfer a current representation of the target resource.

### Method
GET

### Endpoint
[Target resource URI]

### Response
#### Success Response (200)
- **body** (representation) - The current representation of the target resource.

#### Response Example
(No example provided in source.)
```

--------------------------------

### HEAD

Source: https://www.rfc-editor.org/rfc/rfc7231.html

The HEAD method is identical to GET except that the server MUST NOT send a message body in the response. It is used to obtain metadata about the resource without transferring the representation data.

```APIDOC
## HEAD [target resource]

### Description
The HEAD method is identical to GET except that the server MUST NOT send a message body in the response. It is used to obtain metadata about the resource without transferring the representation data.

### Method
HEAD

### Endpoint
[target resource URI]

### Response
#### Success Response (200)
- **headers** (metadata) - Same headers as GET response, but no message body.

#### Response Example
(No explicit example provided in source.)
```

--------------------------------

### GET

Source: https://www.rfc-editor.org/rfc/rfc7231.html

The GET method requests transfer of the current selected representation for the target resource. It is cacheable and can be used for range requests.

```APIDOC
## GET

### Description
The GET method requests transfer of the current selected representation for the target resource. It is cacheable and can be used for range requests.

### Method
GET

### Endpoint
[Target resource URI]

### Parameters
#### Query Parameters
- **Range** (header) - Optional - Used to request a range of the representation.

### Request Example
No request body is defined for GET.

### Response
#### Success Response (200)
- **body** (representation) - The current representation of the target resource.

#### Response Example
[Representation data]

### Notes
- A payload within a GET request has no defined semantics.
- The response is cacheable unless otherwise indicated by Cache-Control.
```

--------------------------------

### OPTIONS

Source: https://www.rfc-editor.org/rfc/rfc7231.html

The OPTIONS method requests information about the communication options available for the target resource or the server. It can be used with an asterisk request-target to test server capabilities, or with a specific resource to discover applicable options.

```APIDOC
## OPTIONS

### Description
The OPTIONS method requests information about the communication options available for the target resource or the server. An asterisk request-target applies to the server in general, while a specific resource applies to that resource.

### Method
OPTIONS

### Endpoint
* (asterisk) or a specific resource URI

### Parameters
#### Request Headers
- **Max-Forwards** (integer) - Optional - Limits the number of proxies or gateways that can forward the request.
- **Content-Type** (media type) - Required if a payload body is sent - Describes the representation media type of the payload.

#### Request Body
- Optional payload body, not defined by this specification but may be used by future extensions.

### Request Example
```
OPTIONS * HTTP/1.1
Host: example.com
```

### Response
#### Success Response (200)
- **Allow** (header) - Optional - Indicates optional features implemented by the server and applicable to the target resource.
- **Content-Length** (header) - Required - Must be "0" if no payload body is sent.
- Payload (optional) - May describe communication options in a machine or human-readable format.

#### Response Example
```
HTTP/1.1 200 OK
Allow: GET, POST, OPTIONS
Content-Length: 0
```

### Notes
- Responses to OPTIONS are not cacheable.
- A proxy MUST NOT generate a Max-Forwards header field unless the request was received with one.
```

--------------------------------

### OPTIONS

Source: https://www.rfc-editor.org/rfc/rfc7231.html

The OPTIONS method requests information about communication options available for the target resource, either from the origin server or an intermediary.

```APIDOC
## OPTIONS [target resource]

### Description
The OPTIONS method requests information about the communication options available for the target resource, at either the origin server or an intervening intermediary. It allows a client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action.

### Method
OPTIONS

### Endpoint
[target resource]

### Parameters
No parameters are explicitly defined in the source.

### Request Example
```
OPTIONS /resource HTTP/1.1
Host: example.com
```

### Response
#### Success Response (200)
- The response typically includes an Allow header listing supported methods, but the source does not specify the exact response format.

### Notes
- The method does not imply a resource action.
```

--------------------------------

### OPTIONS

Source: https://www.rfc-editor.org/rfc/rfc7231.html

The OPTIONS method requests information about the communication options available for the target resource. It is safe and idempotent.

```APIDOC
## OPTIONS [target resource]

### Description
The OPTIONS method requests information about the communication options available for the target resource. It allows a client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action.

### Method
OPTIONS

### Endpoint
[target resource URI]

### Response
#### Success Response (200, 204)
- **Allow** (header) - List of methods supported by the target resource.
- **body** (representation) - Optional communication options.

#### Response Example
(No explicit example provided in source.)
```

--------------------------------

### HEAD

Source: https://www.rfc-editor.org/rfc/rfc7231.html

The HEAD method is identical to GET except that the server MUST NOT send a message body in the response. It is used to obtain metadata about the selected representation.

```APIDOC
## HEAD

### Description
The HEAD method is identical to GET except that the server MUST NOT send a message body in the response. It is used to obtain metadata about the selected representation without transferring the representation data.

### Method
HEAD

### Endpoint
[Target resource URI]

### Parameters
No parameters are explicitly defined.

### Request Example
No request body is defined for HEAD.

### Response
#### Success Response (200)
- **headers** (header fields) - Same header fields as a GET response, except payload header fields MAY be omitted.

#### Response Example
[Header fields only]

### Notes
- A payload within a HEAD request has no defined semantics.
- The response is cacheable unless otherwise indicated by Cache-Control.
```

--------------------------------

### OPTIONS

Source: https://www.rfc-editor.org/rfc/rfc7231.html

Describes the communication options for the target resource. This method is optional for servers to support.

```APIDOC
## OPTIONS

### Description
Describe the communication options for the target resource.

### Method
OPTIONS

### Endpoint
[Target resource URI]

### Response
#### Success Response (200)
- **Allow** (header) - The set of methods allowed by the target resource.

#### Response Example
(No example provided in source.)
```

--------------------------------

### CONNECT

Source: https://www.rfc-editor.org/rfc/rfc7231.html

Establishes a tunnel to the server identified by the target resource. This method is optional for servers to support.

```APIDOC
## CONNECT

### Description
Establish a tunnel to the server identified by the target resource.

### Method
CONNECT

### Endpoint
[Target resource URI]

### Response
#### Success Response (200)
- **tunnel** (connection) - The established tunnel.

#### Response Example
(No example provided in source.)
```

--------------------------------

### PUT

Source: https://www.rfc-editor.org/rfc/rfc7231.html

The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload. A successful PUT suggests that a subsequent GET on the same target resource will result in an equivalent representation.

```APIDOC
## PUT

### Description
The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload. A successful PUT suggests that a subsequent GET on the same target resource will result in an equivalent representation.

### Method
PUT

### Endpoint
[Target resource URI]

### Request Body
The representation enclosed in the request message payload defines the new state of the target resource.

### Response
#### Success Response (200 OK)
A successful PUT of a given representation would suggest that a subsequent GET on that same target resource will result in an equivalent representation being sent in a 200 (OK) response.

### Notes
- There is no guarantee that the representation will be exactly equivalent, but the server should aim for that.
```

--------------------------------

### PUT [Target Resource]

Source: https://www.rfc-editor.org/rfc/rfc7231.html

The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message content. This documentation covers the semantics and expected responses.

```APIDOC
## [PUT] [Target Resource]

### Description
The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message content. This documentation covers the semantics and expected responses.

### Method
PUT

### Endpoint
[Target Resource]

### Parameters
#### Request Body
The request body contains the representation of the target resource to be created or replaced.

### Response
#### Success Response (201 Created)
If the target resource does not have a current representation and the PUT successfully creates one, the origin server MUST send a 201 (Created) response.

#### Success Response (200 OK or 204 No Content)
If the target resource has a current representation and that representation is successfully modified in accordance with the state of the enclosed representation, the origin server MUST send either a 200 (OK) or a 204 (No Content) response.

#### Error Response (409 Conflict or 415 Unsupported Media Type)
When a PUT representation is inconsistent with the target resource, the origin server SHOULD either make them consistent or respond with an appropriate error message. The 409 (Conflict) or 415 (Unsupported Media Type) status codes are suggested, with the latter being specific to constraints on Content-Type values.

### Additional Notes
- An origin server SHOULD ignore unrecognized header fields received in a PUT request (i.e., do not save them as part of the resource state).
- An origin server SHOULD verify that the PUT representation is consistent with any constraints the server has for the target resource that cannot or will not be changed by the PUT.
```

--------------------------------

### POST

Source: https://www.rfc-editor.org/rfc/rfc7231.html

The POST method is used to submit data to a specified resource. It can create new resources, post messages to bulletin boards, or append data to existing representations. The origin server indicates the result via an appropriate status code, typically 201 (Created) for successful creation, and may include a Location header for the primary resource.

```APIDOC
## POST

### Description
The POST method is used to submit data to a specified resource. It can create new resources, post messages to bulletin boards, or append data to existing representations. The origin server indicates the result via an appropriate status code, typically 201 (Created) for successful creation, and may include a Location header for the primary resource.

### Method
POST

### Endpoint
[Target resource URI]

### Response
#### Success Response (201 Created)
- **Location** (string) - Identifier for the primary resource created.
- **Representation** - Describes the status of the request and refers to the new resource(s).

#### Success Response (200 OK)
- **Content-Location** (string) - Same value as the POST's effective request URI, allowing caching of the result for later GET requests.

#### Redirect Response (303 See Other)
- **Location** (string) - Identifier of an existing resource that is equivalent to the result of processing the POST.

### Notes
- Responses to POST are only cacheable when they include explicit freshness information.
- POST caching is not widely implemented.
- Almost all status codes defined by this specification might be received in response to POST, except 206, 304, and 416.
```
Tokens:
Raw