ecfr

Ecfr

Provides a Ruby API client for the eCFR.gov APIs. Not all services and API endpoints in this gem are publically available. See https://www.ecfr.gov/developers/documentation/api/v1 for public endpoint documentation.

Installation

Add this line to your application's Gemfile:

gem 'ecfr'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install ecfr

Usage

Configuration is supported via a configuration block. Only user_agent is required to be configured. See lib/ecfr/configuration.rb for options.

Ecfr.configure do |config|
  config.user_agent = "MyProject([e-mail])"
end

XML parsing

Some endpoints return XML (like the Structure) and will be automatically parsed using Nokogiri. However we do not bundle this as a gem dependency since it may not always be used. To use this you will need to add the Nokogiri gem to your code.

Response caching

Response caching can be enabled via a configuration option. This is a performance feature that allows the calling code to not worry about performance when different parts of the application call the same endpoints at different times in the same request. Responses are cached my HTTP method, api endpoint and requested parameters. You will need to install the request_store gem when enabling this option.

If you are using request store outside of a Rails project or in a background process (eg Sidekiq) check the RequestStore documentation for how to use the required middleware.

Parallel client

A basic parallel client is provided to support some use cases (we use it internally for our status page). This requires the use of faraday-typhoeus adapter. However we do not bundle this as a gem dependency since it may not always be used. To use the parallel client you will need to add the typhoeus faraday adapter gem to your code.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Simple endpoints that return an array of data under a single key

For endpoints that return results like:

{
  items: [
    {name: "Item 1", active: true},
    {name: "Item 2", active: true},
    {name: "Item 3", active: false}
  ]
}

We support a result_key in the definition. In this example result_key: :items. This will cause each item in the items array to be instantiated as an instance of the class and delegate enumerable methods such as .each, .first, .last.

So the following definition:

class Items < Base
  result_key: :items

  attribute :name
  attribute :active, type: boolean

  def self.all
    new(
      get(...)
    )
  end
end

could be used Items.all.each which would iterate through an array of Item instances with name and active (and active?) methods.

More complex endpoints

If however the endpoint returns data more like:

{
  items: [
    {name: "Item 1", active: true},
    {name: "Item 2", active: true},
    {name: "Item 3", active: false}
  ],
  warehouse: "Warehouse 32",
  dock: "Dock A"
}

then we support the following definition:

class Items < Base
  class Item
    include AttributeMethodDefinition

    attribute :name
    attribute :active, type: boolean
  end

  attribute: :items, type: Array(Item)
  attribute: :dock, :warehouse

  def self.all
    new(
      get(...)
    )
  end
end

which can then be used like result = Items.all; result.items.each...; result.warehouse.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/criticaljuncture/ecfr.

License

The gem is available as open source under the terms of the MIT License.