README.md in green-button-data-0.2.1 vs README.md in green-button-data-0.3.0
- old
+ new
@@ -1,17 +1,17 @@
# Green Button Data
-[](https://circleci.com/gh/VerdigrisTech/green-button-data)
[](https://rubygems.org/gems/green-button-data)
+[](https://circleci.com/gh/VerdigrisTech/green-button-data)
[](https://gemnasium.com/VerdigrisTech/green-button-data)
-[](https://codecov.io/github/VerdigrisTech/green-button-data)
[](https://codeclimate.com/github/VerdigrisTech/green-button-data)
+[](https://codecov.io/github/VerdigrisTech/green-button-data)
-Green Button Data is a Ruby gem that can quickly parse the Green Button data
-standard. It uses an event-driven <abbr title="Simple API for XML">SAX</abbr>
-parser which does not build the entire <abbr title="Document Object Model">DOM</abbr>
-in memory.
+Green Button Data is a Ruby gem that can consume Green Button APIs and parse
+the Green Button data XML schema very quickly. It uses an event-driven
+<abbr title="Simple API for XML">SAX</abbr> parser which parses XML data without
+building an entire <abbr title="Document Object Model">DOM</abbr> in memory.
## Getting Started
Add the Green Button Data gem to your Gemfile:
@@ -23,12 +23,105 @@
```bash
$ bundle
```
-## Usage
+Unless you have a project that auto loads all gems in the Gemfile (e.g. a Rails
+project), you will need to require it:
+```ruby
+require 'green-button-data'
+```
+
+This will expose the GreenButtonData module namespace.
+
+## Integrating GreenButtonData Into Your Application
+
+GreenButtonData gem provides a familiar interface to consuming API endpoints.
+Method names are similar to Rails' ActiveRecord models and can be easily
+integrated into existing applications.
+
+### Configuration
+
+You can add configuration options like the following:
+
+```ruby
+GreenButtonData.configure do |config|
+ config.base_url = "https://api.example.com/DataCustodian/espi/1_1/resource/"
+ config.application_information_path = "ApplicationInformation/"
+ config.authorization_path = "Authorization/"
+ config.subscription_path = "Subscription/"
+ config.usage_point_path = "UsagePoint/"
+end
+```
+
+Note that each path _must_ end with a trailing slash.
+
+#### Rails Integration
+
+If you are developing a Rails app, create a file at
+`config/initializers/green_button_data.rb` from your Rails project root and
+add the configuration there.
+
+## Green Button Data API Client
+
+Green Button Data specification states that all API endpoints be secured with
+OAuth2 which means most fetch operations will require auth tokens.
+
+Some endpoints are secured further by utilizing client SSL certificates (e.g.
+Pacific Gas & Electric). You may pass in `ssl` options in addition to
+the `token` option in this case.
+
+> **DISCLAIMER:** Green Button Data is **_NOT_** responsible for managing OAuth
+tokens to make authenticated requests. There are other gems that provide mature,
+production proven OAuth 2 functionalities such as [OmniAuth](https://github.com/intridea/omniauth).
+
+### List all entries
+
+By default, the `.all` method attempts to use the URL path set by configuration:
+
+```ruby
+require 'green-button-data'
+
+# Ideally obtained from OmniAuth gem
+access_token = "12345678-1024-2048-abcdef001234"
+
+# Return all usage points; URL is specified in GreenButtonData.configuration.usage_point_url
+usage_points = UsagePoint.all token: access_token
+```
+
+You may override the global configuration by specifying the URL in the method:
+
+```ruby
+usage_points = UsagePoint.all "https://someotherapi.org/espi/Authorization",
+ token: access_token
+```
+
+### Find an entry by ID
+
+If you have URL defined in configuration, the `.find` method appends the ID to
+the URL:
+
+```ruby
+GreenButtonData.configure do |config|
+ config.base_url = "https://services.greenbuttondata.org/"
+ config.usage_point_path = "DataCustodian/espi/1_1/resource/UsagePoint/"
+end
+
+# GET request to https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/UsagePoint/2
+usage_point = GreenButtonData::UsagePoint.find 2, token: access_token
+```
+
+As with `.all` method, URL can be overridden per request in `.find`:
+
+```ruby
+usage_point = GreenButtonData::UsagePoint.find "https://someotherapi.org/espi/UsagePoint/1",
+ token: access_token
+```
+
+## Parsing
+
Almost all of the functionality for parsing data is wrapped in the
`GreenButtonData::Feed` class.
To parse a Green Button Atom feed, simply call the `parse` method and pass in
the entire XML document:
@@ -59,15 +152,30 @@
2. Create a feature branch: `git checkout -b my-awesome-feature`
3. Make changes and commit: `git commit -am "Add awesome feature"`
4. Push the branch: `git push origin my-awesome-feature`
5. Submit a pull request
+## Versioning
+
+Green Button Data gem follows [Semantic Versioning 2.0](http://semver.org/). As
+such, you can specify a pessimistic version constraint on this gem with two
+digits of precision and be guaranteed latest features and bug fixes without
+backwards breaking changes:
+
+```ruby
+gem 'green-button-data', '~> 0.1'
+```
+
+Exception to this rule as per the SemVer specification is major version zero for
+initial development. This gem's API should NOT be considered stable until 1.0
+release.
+
## License
This software is distributed AS IS WITHOUT WARRANTY under [Simplified BSD](https://raw.githubusercontent.com/VerdigrisTech/green-button-data/master/LICENSE.txt)
license.
Verdigris Technologies Inc. assumes NO RESPONSIBILITY OR LIABILITY
UNDER ANY CIRCUMSTANCES for usage of this software. See the [LICENSE.txt](https://raw.githubusercontent.com/VerdigrisTech/green-button-data/master/LICENSE.txt)
file for detailed legal information.
-Copyright © 2015, Verdigris Technologies Inc. All rights reserved.
+Copyright © 2015, [Verdigris Technologies Inc](http://verdigris.co). All rights reserved.