README.md in bandiera-client-2.2.2 vs README.md in bandiera-client-3.0.0
- old
+ new
@@ -1,15 +1,15 @@
# Bandiera::Client (Ruby)
-This is a client for talking to the [Bandiera][bandiera] feature flagging
-service from a Ruby application.
+This is a client for talking to the [Bandiera][bandiera] feature flagging service from a Ruby application.
This client is compatible with the [v2 Bandiera API][bandiera-api].
-**Current Version:** 2.2.1
-**License:** [MIT][mit]
-**Build Status:** [![Build Status][travis-img]][travis]
+[![Gem version][shield-gem]][info-gem]
+[![Build status][shield-build]][info-build]
+[![Dependencies][shield-dependencies]][info-dependencies]
+[![MIT licensed][shield-license]][info-license]
## Ruby Support:
This client has been tested against the latest MRI and JRuby builds.
@@ -24,76 +24,80 @@
Then interact with a Bandiera server like so:
```ruby
require 'bandiera/client'
-$bandiera = Bandiera::Client.new('http://bandiera.example.com')
+client = Bandiera::Client.new('http://bandiera-demo.herokuapp.com')
+params = {}
-if $bandiera.enabled?('pubserv', 'show-new-search')
+if client.enabled?('pubserv', 'show-new-search', params)
# show the new experimental search function
end
```
-The `$bandiera.enabled?` command takes two arguments - the 'feature group',
-and the 'feature name'. This is because in Bandiera, features are organised
-in groups as it is intented as a service for multiple applications to use at
-the same time - this organisation allows separation of feature flags that are
-intended for different audiences.
+The `client.enabled?` command takes two main arguments - the 'feature group', and the 'feature name'. This is because in Bandiera, features are organised into groups as it is intented as a service for multiple applications to use at the same time - this organisation allows separation of feature flags that are intended for different audiences.
-## Caching
+`client.enabled?` also takes an optional `params` hash, this is for use with some of the more advanced features in Bandiera - user group and percentage based flags. It is in this params hash you pass in your `user_group` and `user_id`, i.e.:
-Bandiera::Client has a small layer of caching built into it in order to:
+```ruby
+client.enabled?('pubserv', 'show-new-search',
+ { user_id: '1234567', user_group: 'Administrators' })
+```
-1. Reduce the amount of HTTP requests made to the Bandiera server
-2. Make things faster
+For more information on these advanced features, please see the Bandiera wiki:
-### Strategies
+https://github.com/nature/bandiera/wiki/How-Feature-Flags-Work#feature-flags-in-bandiera
-There are three request/caching strategies you can use with Bandiera::Client.
+# Performance
-**:single_feature**
+Using the `client.enabled?` method all over your codebase isn't the most efficient way of working with Bandiera as every time you call `enabled?` you will make a HTTP request to the Bandiera server.
-This strategy calls the Bandiera API for each new .enabled? request, and stores
-the response in it's local cache. Subsequent `.enabled?` requests (using the
-same arguments) will read from the cache until it has expired. This is the
-**least** efficient strategy in terms of reducing HTTP requests and speed.
+One way of working more efficiently is using the [Direct API Access](#direct-api-access) methods, to fetch all the feature flags for a given group (or even **all** of the feature flags in the Bandiera server) in one request. You can then hold these as you please in your application and call on the values when needed.
-**:group**
+Another approach is to use the Bandiera::Middleware class supplied in this gem. This can be used in conjunction with other middlewares for identifying your currently logged in user and assigning them a UUID to enable all of the most advanced features in Bandiera very simply.
-This strategy calls the Bandiera API **once** for each feature flag group
-requested, and then stores the resulting feature flag values in the cache.
-This means that all subsequent calls to `.enabled?` for the same group will not
-perform a HTTP request and instead read from the cache until it has expired.
-This is a good compromise in terms of speed and number of HTTP requests, **and
-is the default caching strategy**.
+[See the blog post on cruft.io for more information on how Bandiera::Client is used at Nature.](http://cruft.io)
-**:all**
+<a name="direct-api-access"></a># Direct API Access
-This strategy calls the Bandiera API **once** and fetches/caches all feature
-flag values locally. All subsequent calls to `.enabled?` read from the cache
-until it has expired. This strategy is obviously the most efficient in terms of
-the number of HTTP requests if you are requesting flags from across multiple
-groups, but might not be the fastest if there are **lots** of flags in your
-Bandiera instance.
+If you'd prefer not to use the `enabled?` method for featching feature flag values, the following methods are available...
-#### Changing the Cache Strategy
+Get features for all groups:
```ruby
-$bandiera = Bandiera::Client.new('http://bandiera.example.com')
-$bandiera.cache_strategy = :all
+client.get_all(params)
+ # gives:
+ # {
+ # 'group1' => {
+ # 'feature1' => true,
+ # 'feature2' => false
+ # },
+ # 'group2' => {
+ # 'feature1' => false
+ # },
+ # }
```
-### Cache Expiration
+Get features for a group:
-The default cache lifetime is 5 seconds. If you would like to alter this you
-can do so as follows:
+```ruby
+client.get_features_for_group('pubserv', params)
+ # gives:
+ # {
+ # 'feature1' => true,
+ # 'feature2' => false
+ # }
+```
+Get an individual feature:
+
```ruby
-$bandiera = Bandiera::Client.new('http://bandiera.example.com')
-$bandiera.cache_ttl = 10 # 10 seconds
+client.get_feature('pubserv', 'show-article-metrics', params)
+ # gives: true/false
```
+As with the `enabled?` method the `params` hash is for passing in your `user_group` and `user_id` values if you are using some of the more advanced features in Bandiera.
# Development
1. Fork this repo.
2. Run `bundle install`
@@ -105,7 +109,13 @@
[mit]: http://opensource.org/licenses/mit-license.php
[bandiera]: https://github.com/nature/bandiera
[bandiera-api]: https://github.com/nature/bandiera/wiki/API-Documentation
-[travis]: https://travis-ci.org/nature/bandiera-client-ruby
-[travis-img]: https://travis-ci.org/nature/bandiera-client-ruby.svg?branch=master
+[info-dependencies]: https://gemnasium.com/nature/bandiera-client-ruby
+[info-license]: LICENSE
+[info-gem]: https://rubygems.org/gems/bandiera-client
+[info-build]: https://travis-ci.org/nature/bandiera-client-ruby
+[shield-dependencies]: https://img.shields.io/gemnasium/nature/bandiera-client-ruby.svg
+[shield-license]: https://img.shields.io/badge/license-MIT-blue.svg
+[shield-gem]: https://img.shields.io/gem/v/bandiera-client.svg
+[shield-build]: https://img.shields.io/travis/nature/bandiera-client-ruby/master.svg