[ADP-129] Expect

NOTICE!

Upon further investigation, we have determined that the Expect header and its associated status code are not recommended for typical API design. For more flexible request handling, we recommend using the Prefer header instead (see ADP-136).

Overview

The Expect HTTP header is used by clients to indicate certain expectations about how the server should handle the request. The primary use of this header is to inform the server that the client expects a 100-continue response before sending the request body. This guideline outlines how and when to use the Expect header in our API.

Usage of Expect Header

1. Purpose:

   • The Expect header is primarily used to avoid sending large request bodies to the server when it is not certain that the server will accept the request. By using the Expect: 100-continue header, the client asks the server to verify that it can handle the request before the client sends the request body.

2. Syntax:

   • The header should be used in the following format:

     Expect: 100-continue

3. When to Use:

   • Use the Expect header when sending large payloads, such as file uploads, to minimize the risk of sending data that the server will ultimately reject.
   • It is especially useful in scenarios where network bandwidth is limited or where the cost of sending large amounts of data is high.

4. Server Behavior:

   • Upon receiving a request with the Expect: 100-continue header, the server should:
     1. Respond with a 100 Continue status code if it is ready to receive the request body.
     2. Respond with a final status code (e.g., 417 Expectation Failed, 4xx, or 5xx errors) if it cannot process the request as expected.

5. Client Behavior:

   • The client should:
     1. Wait for a 100 Continue response before sending the request body.
     2. If the server responds with a 417 Expectation Failed or any other error status, the client should not send the request body.
     3. Handle any errors appropriately based on the server's response.

6. Error Responses:

   • All error responses should conform to the HTTP Problem (RFC 9457) specification. Please refer ADP-401: HTTP Problem Basics.

Example

Client Request:

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

[Request body not sent yet]

Server Response (if the server is ready to accept the request body):

HTTP/1.1 100 Continue

Client Action:

• Upon receiving 100 Continue, the client proceeds to send the request body.

Server Response (if the server cannot process the request):

HTTP/1.1 417 Expectation Failed
Content-Type: application/problem+json

{
  "type": "https://example.com/probs/cannot-process",
  "title": "Unable to process request",
  "status": 417,
  "detail": "The server is currently unable to handle the request for this upload size",
  "instance": "/upload/1234"
}

Client Action:

• Upon receiving 417 Expectation Failed, the client aborts the request and does not send the request body.

Reference

• https://www.rfc-editor.org/rfc/rfc9110#field.expect
• https://www.rfc-editor.org/rfc/rfc9457

Changelog

• 2025.01.16: Retiring this for API design