Vimeo API not responding to "If-Modified-Since" header

Question

According to Vimeo API documentation:

The If-Modified-Since header enables you to return only those API resources that have been modified since a particular date and time.

The header looks like this: If-Modified-Since: {ddd}, {D} {MMM} {YYYY} {HH}:{mm}:{ss} {Z} NOTE: If your formatting codes are rusty, Tue, 20 Jun 2023 14:42:36 GMT is an example.

If none of the resources have been modified since this date, the API returns an empty response body and the HTTP status 304 Not Modified.

I'm using the Official PHP library for the Vimeo API.
According to GitHub issue #130, the PHP library's request() method accepts an array of headers. And this commit shows how the $headers array is passed and parsed:

public function request($url, $params = array(), $method = 'GET',
                        $json_body = true, array $headers = array())

// Set the headers
foreach ($headers as $key => $value) {
  $curl_opts[CURLOPT_HTTPHEADER][] = sprintf('%s: %s', $key, $value);
}

But when I pass the future date shown in the example, I still receive a full list of videos rather than the "empty response body and the HTTP status 304 Not Modified" specified in the documentation.

What am I doing wrong?

$fields = array(
  'created_time',
  'modified_time'
);

$params = array(
  'page' => $page,
  'filter' => 'embeddable',
  'filter_embeddable' => true,
  'fields' => implode(',',$fields)
);

$headers = array(
  'If-Modified-Since' => 'Tue, 20 Jun 2023 14:42:36 GMT'
);

$json_body = true;
$method = 'GET';

$response = $vimeo->request('/me/videos', $params, $method, $json_body, $headers);

Result:

Array
(
    [0] => Array
        (
            [created_time] => 2018-06-05T19:27:18+00:00
            [modified_time] => 2018-06-29T19:12:21+00:00
        )

    [1] => Array
        (
            [created_time] => 2016-06-02T03:01:40+00:00
            [modified_time] => 2019-04-30T06:15:29+00:00
        )

    [2] => Array
        (
            [created_time] => 2016-05-29T05:31:46+00:00
            [modified_time] => 2019-04-25T07:46:53+00:00
        )

    ....

---

Edit

Based on this answer (not about Vimeo), it seems that the API might return the entire set of videos if even one of them was modified after the "If-Modified-Since" date.

If anything has changed in the entire response, then it will send the entire response to you.

But I'd still expect the result to be empty if the date is in the future. Am I misunderstanding?

---

Edit

Tom suggested that the Vimeo API ignores "If-Modified-Since" headers that are set in the future. I tried setting mine in the recent past, but I'm still getting results that were modified before that date:

$vimeo = new \Vimeo\Vimeo(false,false,$access_token);

$fields = array(
    'modified_time'
);

$params = array(
    'page' => 1,
    'fields' => implode(',',$fields)
);

$method = 'GET';
$json_body = true;

$headers = array(
    'If-Modified-Since' => 'Fri, 24 May 2019 14:42:36 GMT'
);

$response = $vimeo->request('/me/videos', $params, $method, $json_body, $headers);

echo"<pre>".print_r($response,true)."</pre>";

The result includes:

[21] => Array
  (
    [modified_time] => 2019-05-16T17:22:58+00:00
  )

[22] => Array
  (
    [modified_time] => 2019-05-12T08:07:30+00:00
  )

---

Edit

I was wrong. As mentioned above, I believe the entire response is returned if any item in the response has been modified since the "If-Modified-Since" timestamp. That made it look like the header wasn't working. But I set the timestamp as close as possible to the current time and I did get a "304 Not Modified" response, as Tom reported in his answer below. Others (content producers) also have access to the Vimeo account I'm testing against and I wasn't aware how recently they had modified content.

Answer 1

It's not documented by Vimeo, but I found out by experiment that:

When If-Modified-Since lies in the future, it is ignored.

Otherwise, the header works as expected. But take care of your timezones and possible clock-skew of a few seconds.

Vimeo's modification time is shown in the API response, in my case:

"modified_time": "2019-05-22T09:52:45+00:00",

If-Modified-Since: Wed, 22 May 2019 09:56:25 GMT returns a 304 Not Modified for my situation.

---

I've submitted a support request to Vimeo to clarify or change this behaviour.