ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-354] Client Hints ​

Overview ​

Client Hints is a mechanism designed to provide device information, allowing the server to make optimal decisions for the requesting client. It serves as a more elegant replacement for the traditional User-Agent header, enabling proactive (client-driven) content negotiation.

Client Hints Infrastructure ​

Low Entropy Hints ​

Low entropy hints are those that provide basic, non-sensitive information about the client:

High Entropy Hints ​

High entropy hints provide more detailed or potentially sensitive information about the client. All Client Hints that are not classified as low entropy fall into this category.

Sample Request Header with Client Hints ​

http
GET /data HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate, br, zstd
Accept-Language: en-US,en;q=0.9
Connection: keep-alive
Host: api.example.com
Sec-CH-UA: "Chromium";v="110", "Not A(Brand";v="24", "Google Chrome";v="110"
Sec-CH-UA-Mobile: ?0
Sec-CH-UA-Platform: "macOS"
Sec-Fetch-Dest: empty
Sec-Fetch-Mode: cors
Sec-Fetch-Site: same-origin
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36
downlink: 10
dpr: 2
rtt: 50
sec-ch-device-memory: 8
sec-ch-dpr: 2
sec-ch-viewport-width: 1280
viewport-width: 1280

Server Interaction with Client Hints ​

If a server is designed to interact with Client Hints, it SHOULD return the Accept-CH header in the response, specifying which hints it accepts. However, this requires an extra request. Alternatively, in modern browsers that support Client Hints, a meta tag can be included in the document header to skip the initial request for the server response with Accept-CH.

If the server's Accept-CH differs from the meta tag content, the browser combines the lists.

html
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="Accept-CH" content="DPR, Viewport-Width, Width, Save-Data, Downlink, RTT, Sec-CH-UA-Full-Version, Sec-CH-UA-Platform-Version, Sec-CH-UA-Model">
    <title>Client Hints Test</title>
</head>

Guidance ​

  • SHOULD improve user experience by adapting content based on device capabilities
  • SHOULD enhance performance by reducing unnecessary data transfer
  • SHOULD design for incremental client hints
    • The client might limit the information sent by client hints; the API SHALL react to empty values of client hints.
  • SHOULD be aware of privacy concerns related to high entropy client hints
    • Use low entropy client hints first.
    • If the API is built with a web page, MAY implement a client hint preference UI to let users choose what information to send. The server SHOULD respect these preferences and limit the usage of Accept-CH.
  • SHOULD note that browsers are expected to send HTTP requests with low entropy client hints without specifying them in Accept-CH.
  • SHOULD be aware that Save-Data is defined by user preference. See Delivering Fast and Light Applications with Save-Data

Examples ​

Designing an API with Responses Varying Based on Client Hints ​

Example 1: High DPR Display ​

http
GET /chart-data HTTP/1.1
Host: api.example.com
DPR: 2.0
http
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2048

{
  "chart": "data with high resolution"
}

Example 2: Slow Network Connection ​

http
GET /data HTTP/1.1
Host: api.example.com
Downlink: 0.5
RTT: 100
http
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1024

{
  "data": "subset of full data due to slow network"
}

Example 3: Save-Data Enabled ​

http
GET /articles/12345 HTTP/1.1
Host: api.example.com
Save-Data: on
http
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1536

{
  "id": "12345",
  "title": "Breaking News: Example Event",
  "summary": "A brief summary of the news event.",
  "content": "This is a condensed version of the article content...",
  "images": [
    "https://example.com/images/1-low-res.jpg"
  ]
}

References ​

Changelog ​

  • 2024.09.24 Remove unwanted /api path in the samples