ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-144] Vary ​

Guidance ​

  • API designing SHOULD NOT use Vary; SHOULD use ETag as alternative. See ADP-128: ETag.
  • If Vary must be used, it SHOULD be used carefully and sparingly.
  • When using Vary, MUST ensure that all listed headers are actually used in the content negotiation process.

Rationale ​

While Vary can be useful for content negotiation, it often leads to cache inefficiencies and complexities. Using ETag instead provides a more straightforward and efficient caching mechanism.

Examples ​

Using ETag instead of Vary ​

http
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

When Vary must be used ​

http
HTTP/1.1 200 OK
Content-Type: application/json
Vary: Accept-Language

Considerations ​

  • Using Vary can lead to increased cache misses, especially with CDNs and proxy caches.
  • ETag provides a more precise caching mechanism without the complexities associated with Vary.
  • If content negotiation is necessary, consider alternative designs that don't rely heavily on Vary.
  • ADP-353 Content Negotiation Strategies

References ​