A long-lived project that still receives updates
Ruby client for the Ministry of Justices LAA fee calculator API. A simple interface for transparent calling of the API endpoints to query data and return calculated fee amounts.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Runtime

 Project Readme

RSpec Rubocop Gem Version

Legal Aid Agency Fee Calculator Client

Ruby client for the ministryofjustice/laa-fee-calculator. It enables transparent calling of this API's endpoints, providing a simple interface for querying data, in particular, the primary function of the API, the #calculate endpoint.

Installation

Add this line to your application's Gemfile:

gem 'laa-fee-calculator-client', '~> 1.2.0'

And then execute:

$ bundle

Or install it yourself:

$ gem install laa-fee-calculator-client

Usage

Quick start
# retrieve a calculated value for AGFS scheme 9
client = LAA::FeeCalculator.client
fee_scheme = client.fee_schemes(1)

# using a hash of options
fee_scheme.calculate(
  scenario: 5,
  advocate_type: 'JRALONE',
  offence_class: 'E',
  fee_type_code: 'AGFS_APPEAL_CON',
  day: 1,
  number_of_defendants: 1,
  number_of_cases: 1
)
# => 130.0

# using a block to supply options
fee_scheme.calculate do |options|
  options[:scenario] = 5
  options[:offence_class] = 'E'
  options[:advocate_type] = 'JRALONE'
  options[:fee_type_code] = 'AGFS_APPEAL_CON'
  options[:day] = 1
  options[:number_of_defendants] = 1
  options[:number_of_cases] = 1
end
# => 130.0
Lookup endpoints

Lookup endpoints (advocate_types, offence_classes, scenarios, fee_types, modifier_types, units) respond to a single argument for the id, or options hashes (where id can also be specified explicitly). Any option key specified, except id:, will be converted to a URI param in the resulting request. ids will become part of the URI path itself. Options specified should therefore be available on the ministryofjustice/laa-fee-caclulator

# instantiate a client
client = LAA::FeeCalculator.client
Fee schemes

All other endpoints are queried based on fee scheme so you will need one of these first

# by id
fee_scheme = client.fee_schemes(1)
# or
fee_scheme = client.fee_schemes(id: 1)


# by type and/or date came into force
fee_scheme = client.fee_schemes(type: 'AGFS', case_date: '2018-01-01')
# => AGFS scheme 9 object

fee_scheme = client.fee_schemes(type: 'AGFS', case_date: '2018-04-01')
# => AGFS scheme 10 object
Lookup data
# all
fee_scheme.advocate_types
fee_scheme.scenarios
fee_scheme.offence_classes
fee_scheme.fee_types
fee_scheme.modifier_types
fee_scheme.units
fee_scheme.prices # defaults to first page (of 100)

# filtered
# by id
fee_scheme.advocate_types('JRALONE')
fee_scheme.modifier_types(1)

# by options
fee_scheme.modifier_types(fee_type_code: 'AGFS_APPEAL_CON')
fee_scheme.prices(scenario: 5, advocate_type: 'QC')

# searching (as opposed to query parameters filtering above)
# by attribute values
fee_scheme.scenarios.find_by(code: 'AS000002')
Calculate

see the Quick start

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake to run the tests.

To experiment with the code:

  • clone the API's repo
git clone git@github.com:ministryofjustice/laa-fee-calculator.git
  • setup and run the API locally
  • run bin/console for an interactive prompt in this repo's directory.

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 tags, and push the .gem file to rubygems.org.

Testing

The test suite makes extensive use of the VCR gem to stub requests to the external API. Any examples within a describe block with a :vcr tag will automatically use (or generate) VCR cassettes via an around block - see spec_helper.rb. All cassettes are stored in the spec/vcr directory and automatically named after the spec that produced them. Only new episodes/requests are created.

Note: VCR is configured to require a re-recording of cassettes once a year by default and will cause spec failures if this is not done. This can be disabled - see spec_helper.rb re_record_interval.

To recreate all cassettes:

Alternatively you can run tests against the local version of the API:

# run tests against local API
$ VCR_OFF=true rspec

You can also test against a hosted API by modifying the following in the spec_helper.rb

# run tests against the default remote host
LAA::FeeCalculator.configure do |config|
  config.host = LAA::FeeCalculator::Configuration::LAA_FEE_CALCULATOR_API_V1
end

Caching

Caching can be configured, with optional logging, by providing a cache store:

LAA::FeeCalculator.configure do |config|
  config.cache = Rails.cache
  config.logger = Rails.logger
end

Note:

Contributing

Bug reports and pull requests are welcome on GitHub at ministryofjustice/laa-fee-calculator-client

Publishing

  1. Make required changes, run specs (rerecord vcr cassettes if necessary)

  2. Run bin/ruby_version_test to test against ruby versions (3.0+ supported at present)

  3. Update the VERSION in lib/laa/fee_calculator/version using semantic versioning.

  4. Update the CHANGELOG.md - format/documentation standards specified at top of file.

  5. PR the change, code-review, merge.

  6. Pull master and run rake task below to publish. Note, you will need a rubygems account with gem owner privileges and have configured your ~/.gem/credentials in order for this task to complete successfully.

$ rake release

This rake task automates the following:

$ git push -u origin <branch>
$ git tag -a v<VERSION> -m "Version <VERSION>"
$ git push origin v<VERSION>
$ gem build laa-fee-calculator-client.gemspec
$ gem push laa-fee-calculator-client-<VERSION>.gem

*<VERSION> is the value of LAA::FeeCalculator::VERSION

License

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