A simple look at the cloudflare API with python.

Since we, and a lot of other people, are using CloudFlare for optimization reasons (aka, the easy way out), I thought I would take a look at their API. First thing I looked for was how to purge the cache from command line.

Now, if you don't know why I'd want to do this, let me explain. We have setup codetalk.io as a Django project, with nginx running fastcgi passing it through on localhost which Django is listening to and then responds accordingly.

Now, we usually make some changes here and there, styles and structuring. One of the things CloudFlare does for us, is cache some of our content, mainly CSS and JS. Caching, in this case, means that instead of the request coming all the way down to our server to get the file, it is picked up by CloudFlare that has set a cache time for it sparing us the load of serving it again and again (if you know varnish, they kindda act like a varnish proxy in front of us).

So, CloudFlare needs to know when we have updated our content so it can purge the cache and begin assembling new pieces, so to speak.

Fortunately, for me, CloudFlare has a mighty fine API for all things like this located here.

So, to purge our cache, I set up a alias on the server executing the following:

curl https://www.cloudflare.com/api_json.html \
    -d 'a=fpurge_ts' \
    -d 'tkn=the_API_key_here' \
    -d 'email=the_email_here' \
    -d 'z=the_domain_here' \
    -d 'v=1'

Of course replacing the_API_key_here, the_email_here and the_domain_here with the appropriate values.

So, after that, I started looking a bit more a the documentation, and decided to make a $stats command for our IRC bot, that pulls down the statistics of today.

I wrote this in python, and here's a snippet showing how to do it:

"""
Pull out statistics from CloudFlare, parse it
and output return a string with the traffic breakdown
of today

"""

import urllib
import urllib2
import json


URL = "https://www.cloudflare.com/api_json.html"
API_KEY = "insert the api key here"
SITE = "insert the website/domain here"
MAIL = "insert the email of the account here"

PARAMETERS = {
    'a': 'stats',
    'tkn': API_KEY,
    'email': MAIL,
    'z': SITE,
    'd': '20'
}

def pull_stats(url, parameters):
    """Pull statistics from CloudFlare"""
    req = urllib2.Request(url, data=urllib.urlencode(parameters))
    stats = urllib2.urlopen(req)
    return stats

def parse_stats(stats):
    """Parse the stats from CloudFlare taking in an urllib2 object"""
    req = json.loads(stats.read())
    traffic = req['response']['result']['objs'][0]['trafficBreakdown']
    uniq = traffic['uniques']
    views = traffic['pageviews']
    parsed = "Unique visitors: Regular = %s, Threat = %s, Crawler = %s.\
Pageviews: Regular = %s, Threat = %s, Crawler = %s." % (
        uniq['regular'],
        uniq['threat'],
        uniq['crawler'],
        views['regular'],
        views['threat'],
        views['crawler']
    )
    return parsed
    

if __name__ == "__main__":
    STATS_OBJ = pull_stats(URL, PARAMETERS)
    print parse_stats(STATS_OBJ)

# Output: Unique visitors: Regular = 148, Threat = 24, Crawler = 24. 
# Pageviews: Regular = 563, Threat = 435, Crawler = 45.

You should only need to alter the constants in the beginning, everything else should work fine without any modifications.

This should also serve fine as a base for pulling out data from any of the other API commands accesible. Happy CloudFlare'ing!

Tehnix/CloudFlare API.md