README.md in oxr-0.2.0 vs README.md in oxr-0.4.0
- old
+ new
@@ -1,10 +1,12 @@
# [](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.
+This gem provides a basic interface to the
+[Open Exchange Rates](https://openexchangerates.org) API. At present, only the
+API calls available to free plans have been implemented.
## Installation
Add this line to your application's Gemfile:
@@ -20,91 +22,150 @@
$ gem install oxr
## Usage
-If you have not done so already, sign up for account on [Open Exchange Rates](https://openexchangerates.org). Once you have an account, go to Your Dashboard and locate your App ID.
+If you have not done so already, sign up for account on
+[Open Exchange Rates](https://openexchangerates.org). Once you have an account,
+go to Your Dashboard and locate your App ID.
-Instantiate a new OXR object, passing your App ID as an argument.
+Configure OXR with your App ID by calling `OXR.configure`:
```ruby
-oxr = OXR.new 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+OXR.configure do |config|
+ config.app_id = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+end
```
-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`.
+(If you are using OXR within a Rails application, you will probably want to put
+this in an initializer.)
-Get the latest conversion rates with `OXR#latest`.
+You can get current exchange rates using `OXR.get_rate`:
```ruby
-oxr.latest
+OXR.get_rate 'GBP' # => 0.703087
+OXR.get_rate 'JPY' # => 111.7062
```
+You can also use the `OXR.[]` shortcut method.
+
+```ruby
+OXR['GBP'] # => 0.703087
+```
+
+`OXR.get_rate` accepts an optional keyword argument to retrieve historical
+exchange rates for given dates. The provided date should be an object which
+responds to `#strftime`.
+
+```ruby
+OXR.get_rate 'GBP', on: Date.new(2015, 6, 14) # => 0.642607
+```
+
+You perform more complex operations by using the lower-level API calls. These
+methods return the raw JSON responses returned by Open Exchange Rates (parsed
+using the [json](https://rubygems.org/gems/json) gem).
+
+Get the latest exchange rates with `OXR#latest`.
+
+```ruby
+OXR.latest
+```
+
This will return a JSON object with a structure similar to the following:
```json
{
- "disclaimer": "...",
- "license": "...",
+ "disclaimer": "…",
+ "license": "…",
"timestamp": 1234567890,
"base": "USD",
"rates": {
"AED": 3.672995,
"AFN": 68.360001,
"ALL": 123.0332,
- /* ... */
+ /* … */
+ "ZMK": 5252.024745,
+ "ZMW": 11.332275,
+ "ZWL": 322.387247
}
}
```
-`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.
+Get historical exchange rates for specific dates with `OXR#historical`. This
+method requires you to provide the date you wish to lookup. The date argument
+should respond to `#strftime`.
```ruby
-oxr['GBP'] # => 0.642607
-oxr['JPY'] # => 123.3267
+OXR.historical on: Date.new(2016, 3, 24)
```
-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`.
+Get a list of available currencies with `OXR#currencies`.
```ruby
-oxr.currencies
+OXR.currencies
```
-Get information about your account (including your usage for the current period) with `OXR#usage`.
+Get information about your account including your usage for the current period
+with `OXR#usage`.
```ruby
-oxr.usage
+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:
+Normally, any API call will send a request to Open Exchange Rates. Since your
+plan allows a limited number of requests per month, you probably want to avoid
+this when running in a test environment. You can stub the responses of specific
+API calls by configuring the endpoint for specific calls to use a local file
+instead of an HTTP request. Just provide a JSON file that reflects the payload
+of an actual API call. (You will find usable JSON files in test/fixtures
+included with this gem.)
+When you're done, you can call `OXR.reset_sources` to restore the default behavior.
+
+Below is an example of configuring OXR within a test.
+
```ruby
class SomeTest < Minitest::Test
def setup
- OXR.sources[:latest] = 'test/fixtures/sample_data.json'
+ OXR.configure do |config|
+ config.latest = 'test/fixtures/sample.json'
+ end
end
def teardown
OXR.reset_sources
end
+end
+```
- def test_something
- oxr = OXR.new('XXX')
- assert_equal 42, oxr.latest['rates']['GBP']
- end
+(You might consider doing this in your development environment as well.)
+
+## Upgrading
+
+The interface has changed between the 0.2.0 and 0.3.0 tags. It is no longer
+necessary to instantiate an OXR object. The API calls are available as class
+methods directly on the OXR module.
+
+```ruby
+# Before
+oxr = OXR.new 'YOUR_APP_ID'
+oxr['JPY']
+oxr.usage
+
+# Now
+OXR.configure do |config|
+ config.app_id = 'YOUR_APP_ID'
end
+OXR['JPY']
+OXR.usage
```
-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`.
+(You can still call `OXR.new`, but this behavior will generate a deprecation
+warning.)
## 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.