cartodb-api 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b4935b964b5d6c1696b7d40e4523841b7bb26dd6
-  data.tar.gz: ea948d6ec927b6f216d6acc5b4221d3d2d25a462
+  metadata.gz: 115e7af3d7d8e0810eca5fa32d4fd3157cde35f7
+  data.tar.gz: caa7a9e9f72f208875a127407a7782f3198beed5
 SHA512:
-  metadata.gz: 884bfa172f755b0f343dd7e771c416680e3fc4a0fa96bc664be69fe453fd20d48e6dfd3cfa755103975f576863fb252a75a7f8501e91b486fb326aff1ea0d6ef
-  data.tar.gz: 6cf5f9a1ff09b8744aeae30a09e32d8a374cd47f0480ce00f7cf9ed87f49d206e368674971473ec04c3b1c3c487bf604e4dc21413731263a4e8ab9d0c6c27dab
+  metadata.gz: 7154c5cb5870bf5c627838e7d38db990a8968a0e0b4cd554442f41a01fb9060fded4e1055dd96be054b9ae4e5deab9b35694ca80c860d11eae6642308a03ecb4
+  data.tar.gz: a89fb9e291d0a8ad5d8c689d0a7b855937dc6cdcc1bbad0c50343cb5254921f42c2f099bf5b760ca3c7ba9a64039b896dafc8a6ba8decd2eaad5a3997c200d88

data/README.md

@@ -1,10 +1,8 @@
-[![Code Climate](https://codeclimate.com/github/pablo-co/cartodb-api/badges/gpa.svg)](https://codeclimate.com/github/pablo-co/cartodb-api)
-
-[![Test Coverage](https://codeclimate.com/github/pablo-co/cartodb-api/badges/coverage.svg)](https://codeclimate.com/github/pablo-co/cartodb-api/coverage)
+[![Code Climate](https://codeclimate.com/github/pablo-co/cartodb-api/badges/gpa.svg)](https://codeclimate.com/github/pablo-co/cartodb-api) [![Test Coverage](https://codeclimate.com/github/pablo-co/cartodb-api/badges/coverage.svg)](https://codeclimate.com/github/pablo-co/cartodb-api/coverage)
 
 # CartoDB::Api
 
-CartoDB::Api is an API library for Ruby which acts as a wrapper for [CartoDB's API](cartodb.com). All requests are built using a really simple fluid interface.
+CartoDB::Api is an API library for Ruby which acts as a wrapper for [CartoDB's API](https://cartodb.com/). All requests are built using a really simple fluid interface.
 
 ## Installation
 
@@ -24,7 +22,129 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+All requests need a configuration object. The first thing you need is to create one.
+
+```ruby
+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.
+
+```ruby
+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:
+
+```ruby
+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).
+
+```ruby
+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:
+
+```ruby
+cartodb = CartoDB::Api::Request.new(configuration)
+```
+
+If you have set a default configuration object there's no need of specifying one during creation:
+
+
+```ruby
+cartodb = CartoDB::Api::Request.new
+```
+
+Now you can make requests to the API resources specified in [CartoDB's API](https://cartodb.com/). 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](http://docs.cartodb.com/cartodb-platform/import-api.html):
+
+We define the request.
+```ruby
+cartodb = CartoDB::Api::Request.new
+```
+
+To get all imports.
+```ruby
+cartodb.imports.retrieve
+```
+
+To retrieve a specific import.
+```ruby
+cartodb.imports('<import id>').retrieve
+```
+
+You can also specify the params, headers, body and payload when calling a CRUD method. For example:
+
+```ruby
+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:
+
+```ruby
+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](https://github.com/lostisland/faraday) library, thus files are sent using the `Faraday::UploadIO` class.
+```ruby
+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.
+
+```ruby
+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
 

data/lib/cartodb/api/request.rb

@@ -20,20 +20,28 @@ module CartoDB
         self
       end
 
-      def create(params = nil, headers = nil, body = nil)
-        make_request(:post, params, headers, body)
+      def create(params: nil, headers: nil, body: nil, payload: nil)
+        make_request(:post,
+                     params: params,
+                     headers: headers,
+                     body: body,
+                     payload: payload)
       end
 
-      def update(params = nil, headers = nil, body = nil)
-        make_request(:patch, params, headers, body)
+      def update(params: nil, headers: nil, body: nil, payload: nil)
+        make_request(:patch,
+                     params: params,
+                     headers: headers,
+                     body: body,
+                     payload: payload)
       end
 
-      def retrieve(params = nil, headers = nil)
-        make_request(:get, params, headers)
+      def retrieve(params: nil, headers: nil)
+        make_request(:get, params: params, headers: headers)
       end
 
-      def delete(params = nil, headers = nil)
-        make_request(:delete, params, headers)
+      def delete(params: nil, headers: nil)
+        make_request(:delete, params: params, headers: headers)
       end
 
       protected
@@ -43,17 +51,23 @@ module CartoDB
       end
 
       def client
-        Faraday.new(url: url) do |client|
+        Faraday.new do |client|
           client.params['api_key'] = api_key
           client.response :raise_error
+          client.request :multipart
+          client.request :url_encoded
           client.adapter Faraday.default_adapter
         end
       end
 
-      def make_request(method, params = nil, headers = nil, body = nil)
+      def make_request(method, params: nil, headers: nil, body: nil, payload: nil)
         begin
-          response = client.send(method) do |request|
-            configure_request(request, params, headers, body)
+          response = client.send(method, url, payload) do |request|
+            configure_request(request,
+                              params: params,
+                              headers: headers,
+                              body: body,
+                              payload: payload)
           end
         rescue => e
           rescue_error(e)
@@ -61,9 +75,9 @@ module CartoDB
         parse(response.body)
       end
 
-      def configure_request(request, params = nil, headers = nil, body = nil)
+      def configure_request(request, params: nil, headers: nil, body: nil, payload: nil)
         request.params.merge!(params) if params
-        request.headers['Content-Type'] = 'application/json'
+        request.headers['Content-Type'] = 'application/json' unless payload
         request.headers.merge!(headers) if headers
         request.body = body if body
         request.options.timeout = timeout

data/lib/cartodb/api/version.rb

@@ -1,5 +1,5 @@
 module CartoDB
   module Api
-    VERSION = '0.0.2'
+    VERSION = '0.1.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cartodb-api
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Pablo Cárdenas
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-10-07 00:00:00.000000000 Z
+date: 2015-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler