Using ETags

The Facebook Marketing API now supports Etags on the Graph API. This means that the API can tell you if the data you are querying has changed since you last checked.

Using ETags:

1. When you make a Graph API call, the response header includes an ETag with a value which is the hash of the data returned in the API call. Save this ETag value for use in the next step.
2. Next time you make the same API call, include the If-None-Match request header with the ETag value saved from the first step.
3. If the data has not changed, the response status code will be 304 – Not Modified and no data is returned.
4. If the data has changed since the last query, the data is returned as usual with a new ETag. Save the new ETag value and use it for subsequent calls.

Note: While ETags help reduce the data traffic, the If-None-Match GET will still count against the throttling limits for your app.

The ETag is calculated using the entire response from the API call including its formatting. Developers should be aware that the formatting of API response output may be impacted by the user agent string. Therefore, calls originating from the same client should keep the user agent consistent between calls.

Simple Example:

A simple example to check is the user's adaccounts have changed

Step 1; Determine the ETag for the current data

curl -i "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

The response will be as follows:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
ETag: "7776cdb01f44354af8bfa4db0c56eebcb1378975"
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.149.204
X-FB-Debug: CWbHcogdwUE8saMv6ML+8FacXFrE8ufhjjwxU2dQWaA=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:07:44 GMT
Content-Length: 3273

{"data":[{"id":"act.......

In this example the ETag is "7776cdb01f44354af8bfa4db0c56eebcb1378975", note that the ETag includes the quotes (").

Step 2; Determine if there have been any changes to the data

curl -i -H "If-None-Match: \"7776cdb01f44354af8bfa4db0c56eebcb1378975\"" "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

If nothing has changed the response will be as follows:

HTTP/1.1 304 Not Modified
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.177.190
X-FB-Debug: ImBhat3k07Nez5FvuS2lPWU0U2xxmxD4B3k9ua4Sk7Q=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:09:17 GMT
Content-Length: 0

Note the 304 Not Modified response. If the data had changed a normal API response would be returned.

Batch Example:

A batch example to check is the user's adgroups have changed

Step 1; Determine the ETag for the current data

curl -i "curl -F 'access_token=___' -F 'batch=[ 
  {"method":"GET", "relative_url": "?ids=6003356308839,6004164369439" }, 
  {"method":"GET", "relative_url": "act_12345678/adgroups?campaign_ids=[6003356307839, 6004164259439]"}]'
 https://graph.facebook.com"

The response will contain ETag values as follows:

...{"name":"ETag","value":"\"21d371640127490b2ed0387e8af3f0f8c9eff012\""}...      
...{"name":"ETag","value":"\"410e53bb257f116e8716e4ebcc76df1c567b87f4\""}...

In this example the ETags are "21d371640127490b2ed0387e8af3f0f8c9eff012" and "410e53bb257f116e8716e4ebcc76df1c567b87f4" note that the ETag includes the quotes (").

Step 2; Determine if there have been any changes to the data

curl -F 'access_token=___' -F 'batch=[
  {"method":"GET", "headers":["If-None-Match: \"21d371640127490b2ed0387e8af3f0f8c9eff012\""], "relative_url": "?ids=6003356308839,6004164369439" },
  {"method":"GET",  "headers":["If-None-Match: \"410e53bb257f116e8716e4ebcc76df1c567b87f4\""], "relative_url": "act_12345678/adgroups?campaign_ids=[6003356307839, 6004164259439]"}]' 
https://graph.facebook.com

If nothing has changed the response will be as follows:

[{
    "code": 304,
    .
    .
    .
    "body": null
},
{
    "code": 304,
    .
    .
    .
    "body": null
}]

Note the 304 Not Modified response. If the data had changed a normal API response would be returned.