Validic

Build Status

Stable Version: 0.5.1

Ruby API Wrapper for Validic. It includes the following functionality:

Breaking Changes

• Methods for user provisioning, suspending, and deleting have been renamed
• Methods will now default to initialized values unless overridden in options

Organization

• Organization metadata

Users

• Provision new Validic users
• Update, Suspend, or Delete users
• Get users from organization credentials
• Find user id from authentication token
• Refresh user authentication token

Profiles

• Get profile information from user authentication token
• Create and modify user profiles

Apps

• List available third party apps
• List synced apps for a particular user

Activities

• Fitness, Routine, Nutrition, Sleep, Weight, Diabetes, Biometrics, Tobacco Cessation
• Get activities scoped to user or organization
• Activities from specific sources
• Specified time ranges

Connect

• Create activities as a Validic Connect partner
• Post extra data
• Update or Delete activities by Validic activity id

Latest Endpoint

• Get latest data recorded, regardless of when the activity occurred
• Scope to organization or user level
• Specify start and end points

Installation

Add this line to your application's Gemfile:

gem 'validic'

And then execute:

$ bundle

Or install it yourself as:

$ gem install validic

Usage

Rails 3+

First, instantiate the client.

require 'validic'

# config/initializers/validic.rb
Validic.configure do |config|
  config.api_url          = 'https://api.validic.com'
  config.api_version      = 'v1'
  config.access_token     = 'ORGANIZATION_ACCESS_TOKEN'
  config.organization_id  = 'ORGANIZATION_ID'
end

# Create a Client Object provided you have an initializer
client = Validic::Client.new

Plain ruby

options = {
  api_url:         'https://api.validic.com',
  api_version:     'v1',
  access_token:    'ORGANIZATION_ACCESS_TOKEN',
  organization_id: 'ORGANIZATION_ID'
}
client = Validic::Client.new(options)

Now you can use the wrapper's helper methods to interface with the Validic API.

# Get current organization metadata
client.get_organization

When your requests return an object they are returned as a Validic::Response object. The Validic::Response typically includes summary metadata and an array of record objects.

client.get_routine.summary.results
client.get_routine.records.first.steps

You can pass a hash of options to calls that fetch data.

client.get_routine(start_date: '2015-01-01T00:00:00+00:00')

More Examples

Below are examples of all helper methods.

require 'validic'

# Alternatively you can use an initializer
options = {
  api_url:         'https://api.validic.com',
  api_version:     'v1',
  access_token:    'ORGANIZATION_ACCESS_TOKEN',
  organization_id: 'ORGANIZATION_ID'
}
client = Validic::Client.new options

Organization methods

Get Requests

Get requests will always return a Validic::Response object. It will look like this:

sleeps = client.get_sleep
=> #<Validic::Response:0x007ff3c9e4daa8
 @records=
  [#<Validic::Sleep:0x007ff3c9e4eb60
    @_id="54b9242798b4b18fff00000d",
    @awake=12.0,
    @deep=nil,
    @last_updated="2015-01-16T14:45:59+00:00",
    @light=nil,
    @rem=nil,
    @source="healthy_yet",
    @source_name="HealthyYet",
    @times_woken=nil,
    @timestamp="2015-01-16T14:45:38+00:00",
    @total_sleep=nil,
    @user_id="54a2eda484626bb50a00002c",
    @utc_offset="+00:00">
 @summary=
  #<Validic::Summary:0x007ff3c9e4eea8
   @end_date="2015-01-17T23:59:59+00:00",
   @limit=100,
   @message="Ok",
   @next=nil,
   @offset=0,
   @previous=nil,
   @results=2,
   @start_date="2015-01-15T00:00:00+00:00",
   @status=200,
   @timestamp=nil>>

Now you have access to a Summary object and an array of activity objects. You can step through either object like so:

sleeps.summary
=> #<Validic::Summary:0x007ff3ca2d98d8
 @end_date="2015-01-17T23:59:59+00:00",
 @limit=100,
 @message="Ok",
 @next=nil,
 @offset=0,
 @previous=nil,
 @results=2,
 @start_date="2015-01-15T00:00:00+00:00",
 @status=200,
 @timestamp=nil>


sleeps.summary.status
=> 200


sleeps.records.first
=> #<Validic::Sleep:0x007ff3ca2d9590
 @_id="54b9242798b4b18fff00000d",
 @awake=12.0,
 @deep=nil,
 @last_updated="2015-01-16T14:45:59+00:00",
 @light=nil,
 @rem=nil,
 @source="healthy_yet",
 @source_name="HealthyYet",
 @times_woken=nil,
 @timestamp="2015-01-16T14:45:38+00:00",
 @total_sleep=nil,
 @user_id="54a2eda484626bb50a00002c",
 @utc_offset="+00:00">


sleeps.records.first.awake
=> 12.0

Get current organization

client.get_organization

User methods

Get users from organization credentials

client.get_users

Get user by Validic user id.

client.get_users(user_id: '5499a29b84626b0339000094')

Refresh authentication token

client.refresh_token(user_id: '5499a29b84626b0339000094')

Get user_id from authentication token

client.me(authentication_token: 'L9RFSRnJvkwfiZm8vEc4')

Provision new users

client.provision_user(uid: '123')

With optional profile.

client.provision_user(uid: '123', profile: { gender: 'M' })

Updating a user

client.update_user(user_id: '5499a29b84626b0339000094', uid: '123')

With optional profile.

client.update_user(user_id: '5499a29b84626b0339000094', uid: '123', profile: { gender: 'M' })

Suspend a user

client.suspend_user(user_id: '5499a29b84626b0339000094')

Unsuspend a user

client.unsuspend_user(user_id: '5499a29b84626b0339000094')

Delete a user

client.delete_user(user_id: '5499a29b84626b0339000094')

Profile methods

Get a user profile

client.get_profile(authentication_token: 'L9RFSRnJvkwfiZm8vEc4')

Create a user profile

client.create_profile(authentication_token: 'L9RFSRnJvkwfiZm8vEc4', gender: 'M')

Apps methods

Get a list of available third-party-apps

client.get_org_apps

Get a list of apps a user is synced to

client.get_user_synced_apps(authentication_token: 'L9RFSRnJvkwfiZm8vEc4')

Activity methods

You can also filter the results of the following methods by passing an options hash

Get an array of fitness records

client.get_fitness

Get an array of routine records

client.get_routine

Get an array of nutrition records

client.get_nutritions

Get an array of weight records

client.get_weight

Get an array of diabetes records

client.get_diabetes

Get an array of biometrics records

client.get_biometrics

Get an array of sleep records

client.get_sleep

Get an array of tobacco cessation records

client.get_tobacco_cessations

Get the next page of a Validic::Response

data = client.get_routine(start_date: '2013-01-01', paginated: "true")
data.next

Get the previous page of a Validic::Response

data = client.get_routine(start_date: '2013-01-01', paginated: "true", page: 3)
data.previous

Validic Connect

CRUD Operations

As a Validic Connect partner you have access to all CRUD operations.

Create

client.create_sleep(user_id: 'VALIDIC_USER_ID', activity_id: 'UNIQUE_ACTIVITY_ID', awake: 2, rem: 1, deep: 7)
=>  #<Validic::Sleep:0x007fafcc2cdd40
 @_id="54b93e1b84626b0581000012",
 @activity_id="22323",
 @awake=2.0,
 @deep=7.0,
 @extras=nil,
 @last_updated="2015-01-16T16:36:43+00:00",
 @light=nil,
 @rem=1.0,
 @source="healthy_yet",
 @source_name="Healthy Yet",
 @times_woken=nil,
 @timestamp="2015-01-16T16:36:43+00:00",
 @total_sleep=nil,
 @utc_offset=nil,
 @validated=false>

Update

client.update_sleep(user_id: 'VALIDIC_USER_ID', _id: 'VALIDIC_ACTIVITY_ID', timestamp: DateTime.now.new_offset(0).iso8601, rem: 4)

=> #<Validic::Sleep:0x007fafcc38fd28
 @_id="54b93e1b84626b0581000012",
 @activity_id="22323",
 @awake=2.0,
 @deep=7.0,
 @extras=nil,
 @last_updated="2015-01-16T16:38:23+00:00",
 @light=nil,
 @rem=4.0,
 @source="healthy_yet",
 @source_name="Healthy Yet",
 @times_woken=nil,
 @timestamp="2015-01-16T16:38:02+00:00",
 @total_sleep=nil,
 @utc_offset=nil,
 @validated=false>
[13] pry(main)>

Delete

client.delete_sleep(user_id: 'VALIDIC_USER_ID', _id: 'VALIDIC_ACTIVITY_ID')
=> true

All objects have the same actions as outlined below.

Fitness

client.create_fitness(user_id: 'VALIDIC_USER_ID', activity_id: 'UNIQUE_ACTIVITY_ID', options)
client.update_fitness(user_id: 'VALIDIC_USER_ID', _id: 'VALIDIC_ACTIVITY_ID', options)
client.delete_fitness(user_id: 'VALIDIC_USER_ID', _id: 'VALIDIC_ACTIVITY_ID')

Routine

client.create_routine(user_id: 'VALIDIC_USER_ID', activity_id: 'UNIQUE_ACTIVITY_ID', options)
client.update_routine(user_id: 'VALIDIC_USER_ID', _id: 'VALIDIC_ACTIVITY_ID', options)
client.delete_routine(user_id: 'VALIDIC_USER_ID', _id: 'VALIDIC_ACTIVITY_ID')

Nutrition

client.create_nutrition(user_id: 'VALIDIC_USER_ID', activity_id: 'UNIQUE_ENTRY_ID', options)
client.update_nutrition(user_id: 'VALIDIC_USER_ID', _id: 'UNIQUE_ENTRY_ID', options)
client.delete_nutrition(user_id: 'VALIDIC_USER_ID', _id: 'UNIQUE_ENTRY_ID')

Weight

client.create_weight(user_id: 'VALIDIC_USER_ID', data_id: 'UNIQUE_ENTRY_ID', options)
client.update_weight(user_id: 'VALIDIC_USER_ID', _id: 'UNIQUE_ENTRY_ID', options)
client.delete_weight(user_id: 'VALIDIC_USER_ID', _id: 'UNIQUE_ENTRY_ID')

Diabetes

client.create_diabetes(user_id: 'VALIDIC_USER_ID', activity_id: 'UNIQUE_ACTIVITY_ID', options)
client.update_diabetes(user_id: 'VALIDIC_USER_ID', _id: 'VALIDIC_ACTIVITY_ID', options)
client.delete_diabetes(user_id: 'VALIDIC_USER_ID', _id: 'VALIDIC_ACTIVITY_ID')

Biometrics

client.create_biometrics(user_id: 'VALIDIC_USER_ID', data_id: 'UNIQUE_ENTRY_ID', options)
client.update_biometrics(user_id: 'VALIDIC_USER_ID', _id: 'UNIQUE_ENTRY_ID', options)
client.delete_biometrics(user_id: 'VALIDIC_USER_ID', _id: 'UNIQUE_ENTRY_ID')

Sleep

client.create_sleep(user_id: 'VALIDIC_USER_ID', activity_id: 'UNIQUE_ACTIVITY_ID', options)
client.update_sleep(user_id: 'VALIDIC_USER_ID', _id: 'VALIDIC_SLEEP_ID', options)
client.delete_sleep(user_id: 'VALIDIC_USER_ID', _id: 'VALIDIC_ACTIVITY_ID')

Tobacco Cessation

client.create_tobacco_cessation(user_id: 'VALIDIC_USER_ID', activity_id: 'UNIQUE_ACTIVITY_ID' options)
client.update_tobacco_cessation(user_id: 'VALIDIC_USER_ID', _id: 'VALIDIC_ACTIVITY_ID', options)
client.delete_tobacco_cessation(user_id: 'VALIDIC_USER_ID', _id: 'VALIDIC_ACTIVITY_ID')

You can also create data with your own custom extras as JSON

client.create_fitness(user_id: 'VALIDIC_USER_ID', activity_id: 'UNIQUE_ACTIVITY_ID', extras: "{\"stars\": 3}")

Latest Records

You can also pass an options hash to filter latest results

Pull latest records for specified type

client.latest_routine

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request