Speeding up API requests

WARNING — None of the following will make any sense whatsoever unless you are aware that the open beta for for our new API has begun. Read all the details.

Some of our requests give you a TON of data. And while data is super fun, sometimes, you don’t need that much. We are working on a system that will allow you to limit the response fields we send, but what if you don’t need a response at all?

HTTP allows you make conditional GET requests. These requests let you tell our servers a little bit more about the request you want to make. Currently, we only support one conditional request: If-Modified-Since.

If-Modified-Since

Say you were building a tool to watch for new Staff Pick videos. Without the If-Modified-Since header, you would request all Staff Pick videos and loop through trying to find new videos.

curl -v -H "Authorization : bearer <ACCESS TOKEN>" https://api.vimeo.com/channels/staffpicks/videos

< HTTP/1.1 200 OK
< Date: Wed, 19 Mar 2014 19:31:53 GMT
* Server Apache is not blacklisted
< Server: Apache
< Cache-Control: no-cache, max-age=315360000
< Vary: Accept,Vimeo-Client-Id,Accept-Encoding
< Last-Modified: Wed, 19 Mar 2014 15:29:35 -0400
< Expires: Sat, 16 Mar 2024 19:31:53 GMT
< Content-Length: 5788
< Content-Type: application/vnd.vimeo.video+json
<
{
    total: 7670,
    page: 1,
    per_page: 25,
    paging:
    {
         next: '/channels/staffpicks/videos?page=2',
         previous: null,
         first: '/channels/staffpicks/videos?page=1',
         last: '/channels/staffpicks/videos?page=307'
    },
    data: [ … ] 
}

Notice the response headers. One of these headers is Last-Modified: Wed, 19 Mar 2014 15:29:35 -0400. This tells you the last time a video was added or removed from the Staff Picks Channel. Make a note of this date.

Next time you check for new videos, add the If-Modified-Since header with the current date.

curl -v -H "Authorization : bearer <ACCESS TOKEN>" -H “If-Modified-Since: <CURRENT-DATE>” https://api.vimeo.com/channels/staffpicks/videos

< HTTP/1.1 304 Not Modified
< Date: Wed, 19 Mar 2014 19:54:36 GMT
* Server Apache is not blacklisted
< Server: Apache
< Expires: Sat, 16 Mar 2024 19:54:36 GMT
< Cache-Control: no-cache, max-age=315360000
< Vary: Accept,Vimeo-Client-Id,Accept-Encoding

Notice there isn’t a response body at all, but there is a 304 status code. 304 Not Modified means that nothing has changed since the date you provided. If a video had been added since that date, you will see the full response body. Let’s make one more API request to see this in action. The following example checks for new additions since 1987, significantly predating Vimeo.

curl -v -H "Authorization : bearer <ACCESS TOKEN>" -H “If-Modified-Since: 04-27-1987” https://api.vimeo.com/videos/31436718

< HTTP/1.1 200 OK
< Date: Wed, 19 Mar 2014 19:31:53 GMT
* Server Apache is not blacklisted
< Server: Apache
< Cache-Control: no-cache, max-age=315360000
< Vary: Accept,Vimeo-Client-Id,Accept-Encoding
< Last-Modified: Wed, 19 Mar 2014 15:29:35 -0400
< Expires: Sat, 16 Mar 2024 19:31:53 GMT
< Content-Length: 5788
< Content-Type: application/vnd.vimeo.video+json
<
{
    total: 7670,
    page: 1,
    per_page: 25,
    paging:
    {
         next: '/channels/staffpicks/videos?page=2',
         previous: null,
         first: '/channels/staffpicks/videos?page=1',
         last: '/channels/staffpicks/videos?page=307'
    },
    data: [ … ] 
}

There have definitely been videos added since this date, so the response is identical to a request without the If-Modified-Since header.

If-Modified-Since lets you speed up your app significantly, so you should probably use it whenever you possibly can! Not all collections support these headers just yet, so look for the Last-Modified header. If you need this feature added anywhere, please do let us know.

Next up: Video credits

« Previous Next »