CartoDB::Api
CartoDB::Api is an API library for Ruby which acts as a wrapper for CartoDB's API. All requests are built using a really simple fluid interface.
Installation
Add this line to your application's Gemfile:
gem 'cartodb-api'
And then execute:
$ bundle
Or install it yourself as:
$ gem install cartodb-api
Usage
All requests need a configuration object. The first thing you need is to create one.
configuration = CartoDB::Api::Configuration.new
The configuration defines all the details regarding the API requests.
- timeout: The request timeout in seconds (default: 30).
- protocol: The protocol that will be used for requests (default: https).
- version: The CartoDB API version that is going to be used (default: 1).
- domain: The domain or IP where the API can be found (default: cartodb.com).
- api_key: The CartoDB API key that will be used for authentication.
- account: The CartoDB account from which all requests are going to be made from.
configuration.timeout = 15
configuration.protocol = 'https'
configuration.domain = 'customdomain.com'
configuration.api_key = '<Your API key>'
configuration.account = '<Account>'
If you are trying to use the API available at cartodb.com the only configuration that you need to set is the api_key and account.
To make this configuration the default for all requests:
CartoDB::Api.default_configuration = configuration
For example, you could set the default configuration in an initializer file in your Rails app (config/initializers/cartodb.rb).
configuration = CartoDB::Api:Configuration.new
configuration.api_key = ENV['CARTODB_API_KEY']
configuration.account = '<Account>'
CartoDB::Api.default_configuration = configuration
Making requests
Once you have a configuration object you can create a request:
cartodb = CartoDB::Api::Request.new(configuration)
If you have set a default configuration object there's no need of specifying one during creation:
cartodb = CartoDB::Api::Request.new
Now you can make requests to the API resources specified in CartoDB's API. Resource IDs are specified as arguments and the verbs: create, retrieve, update, and delete initiate the request.
For example to interact with the import resource:
We define the request.
cartodb = CartoDB::Api::Request.new
To get all imports.
cartodb.imports.retrieve
To retrieve a specific import.
cartodb.imports('<import id>').retrieve
You can also specify the params, headers, body and payload when calling a CRUD method. For example:
cartodb.imports.create(
headers: {
some_header: 'header_value'
},
params: {
some_param: 'param_value'
},
body: body,
payload: {
file: Faraday::UploadIO.new('<file>', '<mime type>')
}
)
All requests can be written inline without the need to create a Request object:
CartoDB::Api.imports.retrieve
CartoDB::Api.imports('<import id>').retrieve
Uploading files
To upload files along the request you need to pass a payload. This library uses the excellent Faraday library, thus files are sent using the Faraday::UploadIO
class.
Faraday::UploadIO.new('<file>', '<mime type>')
Please note that the mime type depends on the file you are sending.
For example to create a new import from a csv file.
csv_file = Faraday::UploadIO.new('file.csv', 'text/csv')
CartoDB::Api.imports.create(payload: {file: csv_file})
Handling errors
There are 3 types of errors this gem can raise:
- CartoDB::Api::InvalidConfiguration: This error is raised when the configuration object is invalid or incomplete.
- CartoDB::Api::Error: This error is raised when there's an error related to the API request.
- CartoDB::Api::ParsingError: This error is raised when the request was successful but there was a problem parsing the JSON returned.
To retrieve more information about an error CartoDB::Api::Error
and CartoDB::Api::ParsingError
provide the following attributes: title
, details
, body
, raw_body
and status_code
. Some may not be present depending on the nature of the error.
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake test
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/pablo-co/cartodb-api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
There are also a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. These are detailed in the Contributing guidelines.
License
The gem is available as open source under the terms of the MIT License.