README.md in oxr-0.1.0.1 vs README.md in oxr-0.2.0
- old
+ new
@@ -1,5 +1,7 @@
+# [](https://badge.fury.io/rb/oxr) [](https://travis-ci.org/jparker/oxr)
+
# OXR
This gem provides a basic interface to the [Open Exchange Rates](https://openexchangerates.org) API.
## Installation
@@ -26,24 +28,50 @@
```ruby
oxr = OXR.new 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
```
-The Open Exchange Rates API returns results as JSON objects. OXR parses these (using the [json](https://rubygems.org/gems/json)) and returns the resulting Hashes. To see the exact structure of the responses for different queries, check the [Open Exchange Rates documentation](https://docs.openexchangerates.org/) or examine the sample responses in `test/fixtures`.
+The Open Exchange Rates API returns results as JSON objects. OXR parses these (using the [json](https://rubygems.org/gems/json) gem) and returns the resulting Hashes. To see the exact structure of the responses for different queries, check the [Open Exchange Rates documentation](https://docs.openexchangerates.org/) or examine the sample responses in `test/fixtures`.
Get the latest conversion rates with `OXR#latest`.
```ruby
oxr.latest
```
+This will return a JSON object with a structure similar to the following:
+
+```json
+{
+ "disclaimer": "...",
+ "license": "...",
+ "timestamp": 1234567890,
+ "base": "USD",
+ "rates": {
+ "AED": 3.672995,
+ "AFN": 68.360001,
+ "ALL": 123.0332,
+ /* ... */
+ }
+}
+```
+
+`OXR#[]` is a shortcut for looking up the conversion rate for a single currency without digging through the JSON object returned by `OXR#latest` yourself.
+
+```ruby
+oxr['GBP'] # => 0.642607
+oxr['JPY'] # => 123.3267
+```
+
Get historical conversion rates for specific dates with `OXR#historical`. This method requires you to provide a Date object for the date you wish to query.
```ruby
oxr.historical on: Date.new(2016, 3, 24)
```
+This will return a JSON object with a structure similar to that returned by `OXR#latest`.
+
Get a list of currently supported currencies with `OXR#currencies`.
```ruby
oxr.currencies
```
@@ -51,9 +79,32 @@
Get information about your account (including your usage for the current period) with `OXR#usage`.
```ruby
oxr.usage
```
+
+## Testing
+
+Normally, any API call will result in a live request to Open Exchange Rates. This probably isn't what you want when you're running tests. You can optionally stub the responses of specific API calls by adding an entry to `OXR.sources`. If you want to stop using custom sources, you can restore normal behavior by calling `OXR.reset_sources`. For example:
+
+```ruby
+class SomeTest < Minitest::Test
+ def setup
+ OXR.sources[:latest] = 'test/fixtures/sample_data.json'
+ end
+
+ def teardown
+ OXR.reset_sources
+ end
+
+ def test_something
+ oxr = OXR.new('XXX')
+ assert_equal 42, oxr.latest['rates']['GBP']
+ end
+end
+```
+
+In this example `test/fixtures/sample_data.json` should contain JSON data matching the structure of an actual Open Exchange Rates response. If you want to stop using custom sources, you can restore normal behavior by calling `OXR.reset_sources`.
## 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.