[ADP-352] Conditional Requests

Overview

Conditional requests are HTTP requests that are executed only if certain conditions are met. They are primarily used to improve efficiency and reduce unnecessary data transfer.

Guidance

• APIs SHOULD support conditional requests when appropriate, especially for large resources or frequently accessed data.
• Implementations SHOULD use ETags in combination with If-None-Match and If-Match headers for conditional requests.
• Another method is date-based conditional requests, use Last-Modified in combination with If-Modified-Since and If-Unmodified-Since.
• When implementing conditional requests:
  • GET requests SHOULD use If-None-Match for caching and avoiding unnecessary data transfer.
  • PUT, PATCH, and DELETE requests SHOULD use If-Match to prevent lost updates and ensure data integrity.
• APIs MUST return appropriate status codes for conditional requests:
  • 304 Not Modified for GET requests when the condition is not met.
  • 412 Precondition Failed for PUT, PATCH, or DELETE requests when the condition is not met.
  • The error response MUST comply HTTP Problem(RFC 9457).

Best Practices

• Use conditional requests for large resources or frequently changing data to reduce bandwidth usage.
• Include clear documentation on how conditional requests are supported in your API.
• Ensure that ETag generation doesn't significantly impact performance for frequently accessed resources.

Related ADPs

• ADP-128 ETag
• ADP-131 If-Match
• ADP-133 If-None-Match
• ADP-353 Optimistic Concurrency Control

References

• RFC 9110 - HTTP Semantics (Section 13: Conditional Requests)
• MDN Web Docs - ETag
• ETag v.s. Last-Modified Discussion

Changelog

• 2024.10.01 Add Last-Modified