API tokens for Timetric
With the newest release of our API, we’ve launched a feature to make life easier for developers — API tokens.
From the beginning, we’ve been focussed as much on the developer experience as the user experience, and so our API has been the focus of just as much TLC as the website. One unavoidable issue in using any web API is dealing with authentication, and it’s especially hard to deal with it in a way that simultaneously satisfies
- security concerns
- ease-of-use for the developer
- ease-of-use for the end-user of any third-party apps.
At launch, we supported OAuth, which is a relatively new standard, designed for web services. It tries to solve all three of these problems, particularly with respect to letting end-users use third-party applications safely.
However, OAuth can be quite complex for developers to get started with. And in particular, if you’re just trying to write scripts to experiment with, for your own use, there’s an awful lot of hoops to jump through, even in understanding the basic OAuth workflow.
We also allowed developers to fallback to using their username and password over HTTP Basic Auth — but with strong caveats around it. Using your login credentials for this sort of purpose is a very bad idea.
Basic Auth (over http, rather than https) has almost no security – it’s easy to sniff over insecure connections. And when using login credentials for anything except logging in through a web-browser, you have to leave your password lying around embedded in scripts, or give it to applications, either of which makes it prone to leakage, whether by accidental loss, or by deliberate attempts to steal.
Worse, you can’t revoke your login credentials easily; once someone has stolen them, the only way to prevent them being used is to change your password — and worse still even that that, since they are your primary login credentials, any attacker can change your password before you do, thus completely denying you access to your account.
So, we’ve made a new authentication scheme publically available. This is designed to be much easier for developers to get going with. Our API tokens still use Basic Auth — despite its drawbacks, it’s got two major advantages over OAuth
- it’s supported by almost every http library out there. Whatever your favourite programming language, chances are its http libraries do HTTP Basic already. (This even includes shell script – curl supports Basic Auth out of the box, see below!)
- it involves a single set of credentials which are basically stateless; unlike OAuth you don’t have to worry about going through a dance to set up your tokens.
Essentially, our API tokens can be used as replacement username/password combinations for certain, limited, operations. You can leave these embedded in scripts, or pass them to applications without fear of the consequences; they can’t be used to change your login password, and they are easily revoked if they do leak out.
Our help pages have proper documentation, both on how to generate API tokens and how to use them, but here’s a quick overview. To create an API token, you go to your settings page, where you’ll see this:
If you follow the “Create new” link, you’ll be prompted for a name for the API token (here, I’ll call it “shell script”, since I’m going to use it with a shell script).
And after you’ve created it, the API token will appear in the list on the page.
As you can see, your API token consists of a Key and a Secret, to be used like a Username and Password. These can be used for authenticating with your http library.
If you’re using Python, we’d recommend httplib2. (If you want to restrict yourself to using the Python standard library, see this article)
import httplib2 h = httplib2.Http() h.add_credentials('APITOKEN_KEY', 'APITOKEN_SECRET') url = "https://timetric.com/series/pk6PiWcpTpimhozf0FTjmA/iso.csv" resp, content = h.request(url)
And in shell script you would do this:
curl http://APITOKEN_KEY:APITOKEN_SECRET@timetric.com/path/
To get you started, there’s a couple of libraries out there already for talking to timetric using the API tokens. You can use these directly, or as examples for your own scripts.
Jacob Kaplan-Moss published his timetric library sometime ago, using OAuth. We’ve adapted it to use API tokens as well; until our patches make their way upstream, you can use our fork.
I’ve been playing around with Clojure recently, and my first project has been a library to retrieve data from timetric. You can see it on github, as another example of how to use the API tokens. (But probably not an example of how to write Clojure – any criticisms of my style are welcome, I’m only learning!)
But the great advantage of API tokens is that you don’t really need to go to the hassle of building a whole library or application to query a web service – sometimes all you want is a script. So here’s a shellscript which will poll timetric every 60 seconds for the latest value of a given timeseries (in this case, the Euro/Rupee exchange rate).
KEY="APITOKEN_KEY" SECRET="APITOKEN_SECRET" URL=https://$KEY:$SECRET@timetric.com/series/pk6PiWcpTpimhozf0FTjmA/value/json/ while 1; do curl $URL echo sleep 60 done
We’ve found the ability to explore web-services from the command-line like this is invaluable in developing applications on top of them — we’ve been using these API tokens for some time internally, and we’re happy we can finally make them available to you.
I’ll be following this post up shortly with a couple of exciting things we’ve done in building services on Timetric with API tokens — we’re looking forward to seeing what the rest of the world does with them.
Resolver One and Timetric
Our friends over at Resolver Systems in London have created a great demo where their spreadsheet software, Resolver One, acts as a client to Timetric. Resolver One is the coolest spreadsheet we’ve seen; it’s Python-powered from the ground up, so when you edit your cell values and formulae, you’re actually editing a Python script. Equally, though, you can head straight to the script-editing pane, and work from there and your changes will be reflected in the grid.
From inside your spreadsheet, you can now authenticate with your Timetric account, retrieve series and plot them, and search for series of interest:
Clicking on ‘Fetch Series’ brings the Timetric data into a new sheet where it can be viewed…
… and plotted:
This is a fantastic use for our API, and great for people who want to use Timetric data offline in a spreadsheet.
Head over to their site to find out more!