README.md in thebigdb-1.1.0 vs README.md in thebigdb-1.2.0
- old
+ new
@@ -1,51 +1,43 @@
# TheBigDB Ruby Wrapper
-A simple ruby wrapper for making requests to the API of [TheBigDB.com][0].
+[](http://travis-ci.org/thebigdb/thebigdb-ruby)
+A simple ruby wrapper for making requests to the API of [TheBigDB.com](http://thebigdb.com). [Full API documentation](http://developers.thebigdb.com/api).
+
## Install
gem install thebigdb
-## Usage
+## Simple usage
-Make your requests using this structure:
-
+The following actions return a TheBigDB::StatementRequest object, on which you can add params using ``.with(hash_of_params)``.
+The request will be executed once you call regular methods of Hash on it (``each_pair``, ``[key]``, etc.), or force it with ``execute``.
+The Hash returned represents the server's JSON response.
- TheBigDB::Statement(action, parameters)
+### Search \([api doc](http://developers.thebigdb.com/api#statements-search)\)
+ TheBigDB.search("iPhone").with(page: 2)
+ TheBigDB.search({match: "James"}, "job", "President of the United States")
+ TheBigDB.search({match: "Facebook"}, "job", {match: "Executive"})
-**[action]** => String of the action as described in the API (e.g. "search", "show", ...)
-**[parameters]** => Hash. Request parameters as described in the API. Tip: Arrays like ``["abc", "def"]`` will automatically be converted to ``{"0" => "abc", "1" => "def"}``
+### Create \([api doc](http://developers.thebigdb.com/api#statements-create)\)
+ TheBigDB.create("iPhone 5", "weight", "112 grams")
+ TheBigDB.create("Bill Clinton", "job", "President of the United States").with(period: {from: "1993-01-20 12:00:00", to: "2001-01-20 11:59:59"})
-Examples:
-
- request = TheBigDB::Statement(:search,
- {
- nodes: [{search: ""}, "job", "President of the United States"],
- period: {from: "2000-01-01 00:00:00", to: "2002-01-01 00:00:00"}
- }
- )
+### Show \([api doc](http://developers.thebigdb.com/api#statements-show)\), Upvote \([api doc](http://developers.thebigdb.com/api#statements-upvote)\) and Downvote \([api doc](http://developers.thebigdb.com/api#statements-downvote)\)
- puts request.response
+ TheBigDB.show("id-of-the-sentence")
+ TheBigDB.upvote("id-of-the-sentence")
+ TheBigDB.downvote("id-of-the-sentence")
-Will print something like:
-
- {
- "status" => "success",
- "statements" => [
- {"nodes" => ["Bill Clinton", "job", "President of the United States"], "id" => "8e6aec890c942b6f7854d2d7a9f0d002f5ddd0c0", "period"=>{"from" => "1993-01-20 00:00:00", "to" => "2001-01-20 00:00:00"}},
- {"nodes" => ["George W. Bush", "job", "President of the United States"], "id" => "3f27673816455054032bd46e65bbe4db8ccf9076", "period"=>{"from" => "2001-01-20 00:00:00", "to" => "2009-01-20 00:00:00"}}
- ]
- }
-
That's it!
-## The TheBigDB::Request object
+## TheBigDB::Request object
-Every request you make will return a ``TheBigDB::Request`` object.
+If you want more details on what is sent and what is received, you can use the generic TheBigDB::Statement method. It returns a TheBigDB::Request object.
It has several readable attributes:
request = TheBigDB::Statement(:search, {nodes: ["iPhone", "weight"]})
request.http # Net::HTTP
request.http_request # subclass of Net::HTTPGenericRequest (Net::HTTP::Get or Net::HTTP::Post)
@@ -57,26 +49,32 @@
## Other Features
You can access other parts of the API in the same way as statements:
TheBigDB::User(action, parameters)
- TheBigDB::Toolbox::Unit(action, parameters)
# Examples
TheBigDB::User(:show, {login: "christophe"}).response["user"]["karma"]
- TheBigDB::Toolbox::Unit(:compare, {values: ["100 g", "1.2 kg"]}).response["result"]
You can modify the TheBigDB module with several configuration options:
TheBigDB.api_key = "your-private-api-key" # default: nil
TheBigDB.use_ssl = true # default: false
+ # If true, and a request response has {"status" => "error"}, it will raise a TheBigDB::Request::ApiStatusError exception with the API error code
+ TheBigDB.raise_on_api_status_error = true # default: false
+
# Both of them take a Proc or a Lambda, the TheBigDB::Request instance is passed as argument
- TheBigDB.before_request_execution = ->(request){ Logger.foo(request) } # default: Proc.new{}
- TheBigDB.after_request_execution = ->(request){ Logger.foo(request) } # default: Proc.new{}
+ TheBigDB.before_request_execution = ->(request){ logger.info(request.data_sent) } # default: Proc.new{}
+ TheBigDB.after_request_execution = ->(request){ logger.info(request.data_received) } # default: Proc.new{}
+ # You can also modify the configuration temporarily
+ TheBigDB.with_configuration(use_ssl: true) do
+ # your code here
+ end
+
## Contributing
Don't hesitate to send a pull request !
## Testing
@@ -84,8 +82,5 @@
rspec spec/
## License
This software is distributed under the MIT License. Copyright (c) 2013, Christophe Maximin <christophe@thebigdb.com>
-
-
-[0]: http://thebigdb.com