README.rdoc in simplificator-withings-0.6.10 vs README.rdoc in simplificator-withings-0.7.0

- old
+ new

@@ -1,179 +1,186 @@ -= simplificator-withings - -This is a ruby implementation for the Withings API. Description of the API can be found here: http://www.withings.com/en/api - -== Versions == - -=== 0.6.10 === - -* Do not raise an exception on unknown types of measurement groups. - -=== 0.6.9 === - -* Added support for activities (thanks to invernizzi) - -=== 0.6.8 === - -* updated README (thanks to jmaddi) - -=== 0.6.7 === - -* Swap ruby-hmac for openssl -* Allow string userid in User.authenticate - -=== 0.6.6 === - -Added list_notifications method to user. - -=== 0.6.3 === - -Fixed escaping for parameters. - -=== 0.6.2 === - -Updated Readme and Gemspec - -=== 0.6.0 === - -OAuth implemented. This version is not compatible to previous releases. -Authentication via userid/publickey is not supported anymore. - -=== 0.4.5 === -E-Mail Address is downcased before hashing it (authentication) - -=== 0.4.4 === -Various fixes for the support of Blood Pressure Monitor - -=== 0.4.0 === -Note that this release breaks the API of previous releases: - -=== User.authenticate === - - User.authenticate() has been replaced by User.userlist - -There is no description available and no guarantee on the order that users are returned by the API (and yes, there can be many users for a single Account) -so it seems best to leave the decision to the users of the API. - -The old method is still there but please update your code. It will be removed in the next release. - -=== MeasurementGroup === - - MeasurementGroup#createt_at has been replaced by MeasurementGroup#taken_on - -Created at is usually the timestamp at which a record was created. But MeasurementGroup#created_at was the timestamp when you actually took the measurement. You can also take measurements (via the Web UI on withings.com) which are for a past date. The record is created today, but the measurement -was taken on 2 weeks ago. - -The old method is still there but please update your code. It will be removed in the next release. - -== Installation - -gem install simplificator-withings -gem install ruby-hmac - -== Authentication - -The WBS API now uses OAuth. See the API documentation for details. - -== TODO - -* Integration Test? But i don't want to share my credentials... Perhaps with a test account on withings? Solution from Withings support: - Hi, - - The easiest is that you just create a regular account - (http://start.withings.com), associate it with one scale, then create a user - (like any regular customer). - - Once this is done, the account is activated. You may then go to My - account/My scale and dissociate the scale, the account will stay opened. - That account may be used by who ever you think it should for test purposes - and will not be associated to a specific scale. - - Thanks for your enquiry ! - - fred - -== Remarks - -* The gem is still under development and the API might change a bit. -* Authentication by user_id/public_key is only supported when the user has activated sharing. - He can do this either in the sharing overlay on my.withings.com or - through the api (user.share <LIST OF DEVICES>) after authentication by email/password -* As soon as the user sets sharing to false (user.share = false) the public_key is reset - and upon next activation of sharing a new public_key is assigned. -* All the methods making remote calls can throw Withing::ApiError if something goes wrong - (wrong public_key, missing parameters, ...). - You can find more details on the error by looking at the status code in the error. - -== How To - -Require the API implementation - require 'rubygems' - require 'withings' - -All classes are name-spaced, if your other code allows you can include Withings - include Withings - -Setup - Withings.consumer_secret = '1234' - Withings.consumer_key = 'abcd' - - -A user can be authenticated using user id and oauth token/secret - user = User.authenticate('<YOUR USER ID>', '<YOUR OAUTH TOKEN>', '<YOUR OAUTH TOKEN SECRET>') - - -You can handle subscriptions through the API (all devices currently known => Scale + Blood Pressure Monitor) - user.subscribe_notification('http://foo.bar.com', 'test subscription') -Specify what devices you are interested - user.subscribe_notification('http://foo.bar.com', 'test subscription', Withings::SCALE, Withings::BLOOD_PRESSURE_MONITOR) - - user.describe_notification('http://foo.bar.com') - user.revoke_notification('http://foo.bar.com') - -List notifications is now possible - user.list_notifications - -And finally you can get measurements, after all this is what it's for - user.measurement_groups(:per_page => 10, :page => 1, :end_at => Time.now) - user.measurement_groups(:category => MeasurementGroup::CATEGORY_TARGET) - user.measurement_groups(:last_updated_at => Time.at(12345)) - user.measurement_groups(:start_at => Time.at(12345), :end_at => Time.at(67890)) - user.measurement_groups(:measurement_type => MeasurementGroup::TYPE_FAT) - user.measurement_groups(:device => Withings::SCALE) - -Since 0.6.9 you can also get activities - user.get_activities - - -== Note on keys in hashes - -Keys to constructors (User, MeasurementGroup and NotificationDescription) and methods (User.measurement_groups) -can be either String or Symbol - -== Note on naming convention - -The WBS API has parameter with shortened names (e.g. 'grpid') or names not following a consistent naming pattern. While this -API implementation tries to stick as close to the API as possible it also tries to unify and simplify the parameter names. -The constructors for User, MeasurementGroup and NotificationDescription accept the names provided by the API but convert the names then -to a more "ruby" way. -An exception to this are the "id" and "publickey" parameters for User.new, they are accepted as "user_id" and "public_key" as well. - -== Note on Patches/Pull Requests - -* Fork the project. -* Make your feature addition or bug fix. -* Add tests for it. This is important so I don't break it in a - future version unintentionally. -* Commit, do not mess with rakefile, version, or history. - (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull) -* Send me a pull request. Bonus points for topic branches. - -== Dependencies - -HTTParty is used for making the HTTP requests and Shoulda and Mocha are used for testing. -Thanks for these Gems. - - -== Copyright - -Copyright (c) 2012 simplificator. See LICENSE for details. += simplificator-withings + +This is a ruby implementation for the Withings API. Description of the API can be found here: http://www.withings.com/en/api + +== Versions + +=== 0.7.0 + +* Removed shoulda +* Fixed failing tests +* Refactored Gemspec +* Closed PR from github + +=== 0.6.10 + +* Do not raise an exception on unknown types of measurement groups. + +=== 0.6.9 + +* Added support for activities (thanks to invernizzi) + +=== 0.6.8 + +* updated README (thanks to jmaddi) + +=== 0.6.7 + +* Swap ruby-hmac for openssl +* Allow string userid in User.authenticate + +=== 0.6.6 + +Added list_notifications method to user. + +=== 0.6.3 + +Fixed escaping for parameters. + +=== 0.6.2 + +Updated Readme and Gemspec + +=== 0.6.0 + +OAuth implemented. This version is not compatible to previous releases. +Authentication via userid/publickey is not supported anymore. + +=== 0.4.5 +E-Mail Address is downcased before hashing it (authentication) + +=== 0.4.4 +Various fixes for the support of Blood Pressure Monitor + +=== 0.4.0 +Note that this release breaks the API of previous releases: + +=== User.authenticate + + User.authenticate() has been replaced by User.userlist + +There is no description available and no guarantee on the order that users are returned by the API (and yes, there can be many users for a single Account) +so it seems best to leave the decision to the users of the API. + +The old method is still there but please update your code. It will be removed in the next release. + +=== MeasurementGroup + + MeasurementGroup#created_at has been replaced by MeasurementGroup#taken_at + +Created at is usually the timestamp at which a record was created. But MeasurementGroup#created_at was the timestamp when you actually took the measurement. You can also take measurements (via the Web UI on withings.com) which are for a past date. The record is created today, but the measurement +was taken on 2 weeks ago. + +The old method is still there but please update your code. It will be removed in the next release. + +== Installation + +gem install simplificator-withings +gem install ruby-hmac + +== Authentication + +The WBS API now uses OAuth. See the API documentation for details. + +== TODO + +* Integration Test? But i don't want to share my credentials... Perhaps with a test account on withings? Solution from Withings support: + Hi, + + The easiest is that you just create a regular account + (http://start.withings.com), associate it with one scale, then create a user + (like any regular customer). + + Once this is done, the account is activated. You may then go to My + account/My scale and dissociate the scale, the account will stay opened. + That account may be used by who ever you think it should for test purposes + and will not be associated to a specific scale. + + Thanks for your enquiry ! + + fred + +== Remarks + +* The gem is still under development and the API might change a bit. +* Authentication by user_id/public_key is only supported when the user has activated sharing. + He can do this either in the sharing overlay on my.withings.com or + through the api (user.share <LIST OF DEVICES>) after authentication by email/password +* As soon as the user sets sharing to false (user.share = false) the public_key is reset + and upon next activation of sharing a new public_key is assigned. +* All the methods making remote calls can throw Withing::ApiError if something goes wrong + (wrong public_key, missing parameters, ...). + You can find more details on the error by looking at the status code in the error. + +== How To + +Require the API implementation + require 'rubygems' + require 'withings' + +All classes are name-spaced, if your other code allows you can include Withings + include Withings + +Setup + Withings.consumer_secret = '1234' + Withings.consumer_key = 'abcd' + + +A user can be authenticated using user id and oauth token/secret + user = User.authenticate('<YOUR USER ID>', '<YOUR OAUTH TOKEN>', '<YOUR OAUTH TOKEN SECRET>') + + +You can handle subscriptions through the API (all devices currently known => Scale + Blood Pressure Monitor) + user.subscribe_notification('http://foo.bar.com', 'test subscription') +Specify what devices you are interested + user.subscribe_notification('http://foo.bar.com', 'test subscription', Withings::SCALE, Withings::BLOOD_PRESSURE_MONITOR) + + user.describe_notification('http://foo.bar.com') + user.revoke_notification('http://foo.bar.com') + +List notifications is now possible + user.list_notifications + +And finally you can get measurements, after all this is what it's for + user.measurement_groups(:per_page => 10, :page => 1, :end_at => Time.now) + user.measurement_groups(:category => MeasurementGroup::CATEGORY_TARGET) + user.measurement_groups(:last_updated_at => Time.at(12345)) + user.measurement_groups(:start_at => Time.at(12345), :end_at => Time.at(67890)) + user.measurement_groups(:measurement_type => MeasurementGroup::TYPE_FAT) + user.measurement_groups(:device => Withings::SCALE) + +Since 0.6.9 you can also get activities + user.get_activities + + +== Note on keys in hashes + +Keys to constructors (User, MeasurementGroup and NotificationDescription) and methods (User.measurement_groups) +can be either String or Symbol + +== Note on naming convention + +The WBS API has parameter with shortened names (e.g. 'grpid') or names not following a consistent naming pattern. While this +API implementation tries to stick as close to the API as possible it also tries to unify and simplify the parameter names. +The constructors for User, MeasurementGroup and NotificationDescription accept the names provided by the API but convert the names then +to a more "ruby" way. +An exception to this are the "id" and "publickey" parameters for User.new, they are accepted as "user_id" and "public_key" as well. + +== Note on Patches/Pull Requests + +* Fork the project. +* Make your feature addition or bug fix. +* Add tests for it. This is important so I don't break it in a + future version unintentionally. +* Commit, do not mess with rakefile, version, or history. + (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull) +* Send me a pull request. Bonus points for topic branches. + +== Dependencies + +HTTParty is used for making the HTTP requests and Shoulda and Mocha are used for testing. +Thanks for these Gems. + + +== Copyright + +Copyright (c) 2012 simplificator. See LICENSE for details.