[ADP-368] HTTP Expect

Guidance

• Servers SHOULD respond appropriately to requests containing the Expect header.
• Clients SHOULD use the Expect header judiciously to improve efficiency and reliability of large or critical requests.

Please refer to ADP-129 for header specific principles.

Example

HTTP Request and Response

POST /large-upload HTTP/1.1
Host: api.example.com
Content-Type: application/octet-stream
Content-Length: 1000000
Expect: 100-continue

[Request body not sent yet]

Server response:

HTTP/1.1 100 Continue

[Client can now send the request body]

OpenAPI 3.1.0 Example

openapi: 3.1.0
paths:
  /large-upload:
    post:
      summary: Upload a large file
      consumes:
        - application/octet-stream
      headers:
        Expect:
          description: Expect header for large uploads
          schema:
            type: string
            enum:
              - 100-continue
      responses:
        '100':
          description: Continue with the request body
        '417':
          description: Expectation Failed

Best Practices

1. Use the Expect header for large payload uploads to avoid unnecessary data transfer if the server is likely to reject the request.
2. Implement proper timeout handling on both client and server sides when using the Expect header.
3. Consider using the Expect header in conjunction with other headers like Content-Length to give the server more information for decision-making.

References

• RFC 9110 Section 10.1.1: Expect
• MDN Web Docs: Expect