ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-149] If-Unmodified-Since ​

reviewing phase 1

It should be mentioned that If-Unmodified-Since is ignored when If-None-Match is processed.

Overview ​

The If-Unmodified-Since HTTP request header is used for conditional requests, allowing the client to send a request only if the resource has not been modified since the specified date.

Guidelines ​

  • API designers SHOULD consider implementing support for the If-Unmodified-Since header in PUT and DELETE requests for modifiable resources.
  • The server MUST compare the date in the If-Unmodified-Since header with the last modified date of the requested resource.
  • If the resource has been modified since the specified date, the server MUST return a 412 (Precondition Failed) status code.
  • If the resource has not been modified since the specified date, the server MUST execute the request and return the appropriate status code.
  • The client SHOULD include the If-Unmodified-Since header when requesting resources that may have been modified.
  • DRAFT Depending on the requirements, if implementing If-Unmodified-Since, it SHOULD be marked as required or optional in the documentation.
    • If marked as required, it SHOULD reject requests without If-Unmodified-Since.

Usage ​

The If-Unmodified-Since header is typically used in PUT or DELETE requests. The client includes this header with a date value in the request, and the server compares this date with the last modified date of the requested resource.

Format ​

http
If-Unmodified-Since: <Day Name>, <Day> <Month> <Year> <Hour>:<Minute>:<Second> GMT

For example

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

Server Behavior ​

When the server receives a request with the If-Unmodified-Since header:

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

    • The server SHOULD respond with a 412 (Precondition Failed) status code.
    • The response body SHOULD be empty.

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

    • The server SHOULD execute the request and return the appropriate status code.

Example ​

Request ​

http
PUT /example.json HTTP/1.1
Host: api.example.com
If-Unmodified-Since: Wed, 21 Oct 2015 07:28:00 GMT
Content-Type: application/json
{
  "example": "Updated content"
}

Response (Modified) ​

http
HTTP/1.1 412 Precondition Failed
Date: Thu, 22 Oct 2015 08:30:00 GMT

Response (Unmodified) ​

http
HTTP/1.1 200 OK
Date: Thu, 22 Oct 2015 08:30:00 GMT
Content-Type: application/json
{
  "example": "Updated content"
}
  • Last-Modified: Response header, indicating the time the resource was last modified.
  • ETag: Response header, providing a unique identifier for a specific version of the resource.
  • If-None-Match: Request header, used in conditional requests with ETag.
  • ADP-148: Cache-Control

References ​