ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-132] If-Modified-Since ​

reviewing phase 1

Should mention ignoring If-Modified-Since if If-None-Match is addressed

Overview ​

The If-Modified-Since HTTP request header is used to make conditional requests, allowing servers to send responses only if the requested resource has been modified since the specified date.

Guidance ​

  • API designers SHOULD implement support for the If-Modified-Since header in GET and HEAD requests for cacheable resources.
  • Servers MUST compare the date in the If-Modified-Since header with the last modification date of the requested resource.
  • Servers MUST return a 304 (Not Modified) status code if the resource has not been modified since the specified date.
  • Servers MUST return a 200 (OK) status code with the updated resource if it has been modified since the specified date.
  • Clients SHOULD include the If-Modified-Since header in requests for resources that may have been cached.
  • Implementers SHOULD use the If-Modified-Since header in conjunction with other caching mechanisms like ETags for more robust caching strategies.

Usage ​

The If-Modified-Since header is typically used in GET or HEAD requests. The client includes this header with a date value, and the server compares this date with the last modification date of the requested resource.

Format ​

http
If-Modified-Since: <day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT

Example:

http
If-Modified-Since: Wed, 21 Oct 2015 07:28:00 GMT

Server Behavior ​

When a server receives a request with an If-Modified-Since header:

  1. If the resource has not been modified since the specified date:

    • The server should respond with a 304 (Not Modified) status code.
    • The response body should be empty.

  2. If the resource has been modified since the specified date:

    • The server should respond with a 200 (OK) status code.
    • The response should include the updated resource in the body.

Example ​

Request ​

http
GET /example.json HTTP/1.1
Host: api.example.com
If-Modified-Since: Wed, 21 Oct 2015 07:28:00 GMT

Response (Not Modified) ​

http
HTTP/1.1 304 Not Modified
Date: Thu, 22 Oct 2015 08:30:00 GMT

Response (Modified) ​

http
HTTP/1.1 200 OK
Date: Thu, 22 Oct 2015 08:30:00 GMT
Content-Type: application/json
Last-Modified: Thu, 22 Oct 2015 08:00:00 GMT

{
  "example": "Updated content"
}
  • Last-Modified: Response header indicating when the resource was last modified.
  • ETag: Response header providing a unique identifier for a specific version of a resource.
  • If-None-Match: Request header used in conjunction with ETag for conditional requests.
  • ADP-131: Cache-Control

References ​