Simple vs Preflighted Requests

Technical Deep Dive & Specifications

The Strict Criteria for a "Simple Request"

According to the WHATWG Fetch Living Standard, a cross-origin request qualifies as a Simple Request (and avoids the preflight OPTIONS round-trip) only if ALL of the following four conditions are met:

1. HTTP Method: Must be one of the three safelisted methods:
   • GET
   • HEAD
   • POST
2. Request Headers: May only contain CORS-safelisted request headers:
   • Accept
   • Accept-Language
   • Content-Language
   • Content-Type (restricted to specific values below)
   • Range (simple range headers)
3. Content-Type Restriction: If Content-Type is present, its value must be strictly one of:
   • application/x-www-form-urlencoded
   • multipart/form-data
   • text/plain
4. No ReadableStream upload: No streaming request body is used, and no XMLHttpRequestUpload event listeners (other than progress, load, etc.) are attached.

+------------------------------------------------------------------------------------+
|  🚨 CRITICAL NOTICE: application/json IS NOT A SIMPLE CONTENT-TYPE!                |
|                                                                                    |
|  Sending fetch('https://api.com', {                                                |
|    method: 'POST',                                                                 |
|    headers: { 'Content-Type': 'application/json' }, // <-- TRIGGERS PREFLIGHT!     |
|    body: JSON.stringify({ user: "Alice" })                                         |
|  });                                                                               |
+------------------------------------------------------------------------------------+

Preflight Request & Response Handshake Anatomy

When any condition above is violated (e.g., method is PUT, DELETE, PATCH, or custom headers like Authorization: Bearer ... or X-Api-Key are included), the browser executes the two-phase Preflight Handshake:

+------------------------------------------------------------------------------------+
|                          THE PREFLIGHT OPTIONS HANDSHAKE                           |
+------------------------------------------------------------------------------------+
|  PHASE 1: PREFLIGHT PROBE                                                          |
|  Client Browser -------------------------------------------------> Origin Server   |
|  OPTIONS /v2/records/89 HTTP/1.1                                                   |
|  Host: api.example.com                                                             |
|  Origin: https://frontend.app.com                                                  |
|  Access-Control-Request-Method: DELETE                                             |
|  Access-Control-Request-Headers: authorization, content-type                       |
|                                                                                    |
|  Origin Server --------------------------------------------------> Client Browser   |
|  HTTP/1.1 204 No Content (or 200 OK)                                               |
|  Access-Control-Allow-Origin: https://frontend.app.com                             |
|  Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS                     |
|  Access-Control-Allow-Headers: Authorization, Content-Type                         |
|  Access-Control-Max-Age: 86400  <-- (Cache preflight approval for 24 hours)        |
|                                                                                    |
|  PHASE 2: THE ACTUAL DISPATCH (Only executed if Phase 1 succeeds!)                 |
|  Client Browser -------------------------------------------------> Origin Server   |
|  DELETE /v2/records/89 HTTP/1.1                                                    |
|  Host: api.example.com                                                             |
|  Origin: https://frontend.app.com                                                  |
|  Authorization: Bearer eyJhbGciOi...                                               |
|                                                                                    |
|  Origin Server --------------------------------------------------> Client Browser   |
|  HTTP/1.1 200 OK                                                                   |
|  {"deleted": true, "recordId": 89}                                                 |
+------------------------------------------------------------------------------------+

Preflight Decision Matrix

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Lines 50–54: Reads user inputs (HTTP method, Content-Type selection, and custom header checkboxes).
• Lines 61–64: Validates the HTTP method against the WHATWG safelist (GET, POST, HEAD). Methods like DELETE or PUT fail this test.
• Lines 66–69: Evaluates the Content-Type. If it is application/json, it triggers the preflight requirement.
• Lines 71–73: Checks for custom headers like Authorization or X-Api-Key.
• Lines 84–97: Displays the resulting network trace, explaining whether the browser sends one direct HTTP request or executes an advance OPTIONS handshake.

Expected Browser Render Output

⚡ CORS Preflight Classifier & Network Inspector
[ HTTP Method: DELETE ]
[ Content-Type: application/json ]
[ [x] Authorization: Bearer ... ]

[ Analyze Network Request Trajectory ]

[ Output Box - Red Background ]:
🔴 CLASSIFICATION: PREFLIGHTED REQUEST (2 Network Round-Trips)

Preflight Trigger Factors:
• Method 'DELETE' is not a CORS-safelisted method (GET, POST, HEAD).
• Content-Type 'application/json' is not a CORS-safelisted MIME type.
• Custom headers [Authorization] are not CORS-safelisted.

Execution Flow:
1. Browser issues: OPTIONS /endpoint HTTP/1.1
   Access-Control-Request-Method: DELETE
   Access-Control-Request-Headers: content-type, authorization
2. Server must respond with HTTP 204 No Content + Access-Control-Allow-Methods/Headers.
3. Browser only dispatches actual DELETE request if preflight succeeds!