swivel2.rb
swivel2.rb is a small library that lets you interface with Swivel’s REST API. We’ve only run the Swivel gem on Linux and OSX platforms, though it may work on others.
You can always find the latest documentation for the Swivel API online at inviteonly.swivel.com/developer
The Swivel API
The Swivel API is RESTful. At this time, you can perform CRUD operations on data_set resources, which allows you to get your data into Swivel and keep it updated. You can also retrieve your data as CSV.
----------- ----------- ------------
HTTP Method URI Description
----------- ----------- ------------
POST /data_sets Create a new data set (upload data)
DELETE /data_sets/#{id} Delete data set #{id}
GET /data_sets List data sets
GET /users/huned/data_sets List huned's data sets
GET /data_sets/#{id} Show data_set #{id}
PUT /data_sets/#{id} Update data_set #{id}
Most method calls take parameters. Check out the Swivel API Documentation for the most up to date documentation. More REST resources will become available as the Swivel API matures.
Installing
$ sudo gem install -y swivel
Successfully installed swivel, version 0.0.103
Installing ri documentation for swivel-0.0.103...
Installing RDoc documentation for swivel-0.0.103...
You need an API key
You need an API key to perform any POST, PUT, or DELETE requests. You must also use an API key to perform a GET request to access your private or shared data. GET requests on public resources (such as users, or public data) do not require an API key. But it never hurts to always send it. Get your API key from inviteonly.swivel.com/developer. Please treat your API key as you would a password.
Your API key is stored in ~/.swivelrc along with some other information. Copy the swivelrc.default provided with this gem to ~/.swivelrc and modify site parameter to include your API key. Please make sure you set appropriate permissions on your ~/.swivelrc file to prevent others from seeing your API key.
An example ~/.swivelrc:
$ cat ~/.swivelrc
--- !ruby/struct:Swivel2::Config
site: http://x:<YOUR API KEY>@api.swivel.com
timeout_read: 500
timeout_write: 1_000
extra_params: { noviews: true }
TODO: describe what each parameter means.
Examples
Basic set up
Before you can use this library, you need to know a bit about the Config and Connection classes. After you set up your ~/.swivelrc, you can run these examples through irb.
$ irb
>> require 'swivel2'
=> true
A Config instance encapsulates important settings stored in your ~/.swivelrc file.
>> config = Swivel2::Config.load '/home/huned/.swivelrc'
=> #<struct Swivel2::Config ...>
A Connection instance is your main interface to Swivel’s API. Construct a Connection instance by passing a Config instance into the constructor.
>> connection = Swivel2::Connection.new config
=> #<Swivel2::Connection:0xb7b34a54 ...>
The Connection class defines post, get, put, and delete methods that you can call with paths to REST resources. These methods automatically send your API key with each request. For example:
>> data_sets = connection.get '/data_sets'
You can also construct a Swivel2::Connection without passing a config option to get a read-only connection that can only access public resources on Swivel.
Data sets
Show a data set
You can show a data set’s XML by making a get call to its resource path:
>> data_set = connection.get '/data_sets/1234567'
=> #<Swivel2::Response::DataSet:0xb79fd244 ...>
You don’t need to go through the Swivel gem to get a data set’s csv. It’s simply a GET:
GET http://api.swivel.com/data_sets/1234567.csv?api_key=<YOUR API KEY>
When getting the CSV, you can optionally specify limit and offset parameters.
List data sets
>> data_sets = connection.get '/data_sets'
You can also list data sets for a specific user. For example, to list huned’s data sets:
>> data_sets = connection.get '/users/huned/data_sets'
When you list data sets, you can optionally provide limit and offset parameters to page through the results. For example, to list data sets 11 through 20:
>> data_sets = connection.get '/data_sets', :limit => 10, :offset => 10
Uploading new data
You just need a CSV and a name for your data set before you can upload it. Without specifying any other options, Swivel will try to figure out the column structure and types automatically.
>> params = {'file[data]' => `cat ~/data.csv`, 'data_set[name]' => 'My Data'}
>> data_set = connection.post '/data_sets', params
=> #<Swivel2::Response::DataSet:0xb7e0051c ...>
See the full list of options that you can use for POST and PUT to /data_sets.
Updating an existing data set’s attributes
>> params = {'data_set[name]' => 'new name'}
>> data_set = connection.put '/data_sets/1234567', params
=> #<Swivel2::Response::DataSet:0xb7e0051c ...>
See the full list of options that you can use for POST and PUT to /data_sets.
Appending more data to an existing data set
>> params = {'file[mode]' => 'append', 'file[data]' => `cat ~/more_data.csv`}
>> data_set = connection.put '/data_sets/1234567', params
=> #<Swivel2::Response::DataSet:0xb7e0051c ...>
See the full list of options that you can use for POST and PUT to /data_sets. Caveat: Your new data must have the same column structure as the original data.
Replacing data for an existing data set
>> params = {'file[mode]' => 'replace', 'file[data]' => `cat ~/new_data.csv`}
>> data_set = connection.put '/data_sets/1234567', params
=> #<Swivel2::Response::DataSet:0xb7e0051c ...>
See the full list of options that you can use for POST and PUT to /data_sets. Caveat: Your new data must have the same column structure as the original data.
Deleting a data set
>> data_set = connection.delete '/data_sets/1234567'
=> #<Swivel2::Response::DataSet:0xb7e0051c ...>
Quickest way to upload? The Swivel command line tool
The Swivel command line tool the quickest way to get your data into Swivel and keep it updated if you have basic Unix and shell scripting knowledge.
Installing the Swivel gem also installs a command line tool, /usr/bin/swivel, that you can use to upload and update data sets without writing a single line of ruby code.
Before using this tool, please set up your ~/.swivelrc as described at the beginning of this documentation.
$ which swivel
/usr/bin/swivel
Aside from being useful on its own, the command line tool is also a nice example of how to write ruby code that uses this gem.
Uploading new data
$ cat data.csv | /usr/bin/swivel upload "my data"
uploaded 1234567
Appending more data to an existing data set
$ cat more_data.csv | /usr/bin/swivel append 1234567
appended 1234567
Caveat: Your new data must have the same column structure as the original data.
Replacing data for an existing data set
$ cat more_data.csv | /usr/bin/swivel replace 1234567
replaced 1234567
Caveat: Your new data must have the same column structure as the original data.
More options
$ /usr/bin/swivel --help
Feedback
Feedback, comments, and (especially) patches welcome at [email protected].
You can rcov this code by running rcov from the top level directory:
$ rcov -Ilib -t test/*_test.rb
License
This software is licensed under the exact same license as Ruby itself.