withings-api is an easy to use Ruby library providing access to the Withings Body Metrics Services API (WBS API) version 2.

For complete details about the WBS API, see www.withings.com/en/api/wbsapiv2

*NOTE, THIS IS A WORK IN PROGRESS, IMPLEMENTATION ISN’T COMPLETE AS OF VERSION 0.0.1*

For an example use of the withings-api, see {file:examples/create_access_token.rb examples/create_access_token.rb}.

Broadly speaking, there are two phases to using the withings-api.

1. Retrieve access to user’s data via OAuth authentication + authorization

   • see {file:README.rdoc#OAuth_Authorization OAuth Authorization} section below.

2. Retrieve user data via authorized OAuth credentials (called “access token” in this documentation).

   • NOTE: This isn’t implemented as of version 0.0.1.

Before you can access user data via the WBS API, you need to go through a process that allows the user to authorize your application’s access to their data. This process is handled by a protocol called OAuth 1.0.

For details on Withings implementation of OAuth, see {www.withings.com/en/api/oauthguide Withings OAuth Guide}. For the complete specification of OAuth 1.0, see {tools.ietf.org/html/rfc5849}.

Broadly, these are the steps to getting access to user data via the API.

1. (One Time) Register you application with Withings - oauth.withings.com/en/partner/add

   • This will give you a “consumer token” and “consumer secret” which is used to identify and authenticate your application

   • Some more information about this step, see {www.withings.com/en/api/oauthguide#registration Withings OAuth Guide: Registration}

2. Request a temporary “request token” used to identify your request for OAuth authorization.

   • Facilitated by {Withings::Api::OAuthActions#create_request_token}.

3. Using the “request token”, redirect the user to Withings to allow them to log in and authorize your access to their data.

   • Use {Withings::Api::RequestTokenResponse#authorization_url} to get the URL to use.

   • Note: this redirect happens outside of withings-api, usually in your webapp.

   • When the user authorizes the request, Withings will redirect the user back to your application:

     • You specify this callback URL in the call to {Withings::Api::OAuthActions#create_request_token}

4. Request permanent access to the users data with an “access token”.

   • Facilitated by {Withings::Api::OAuthActions#create_access_token}

5. Now you have permanent credentials to use when making calls that access user data.

Once authorized, you can use data access methods for retreiving user Withings data.

**Implementation and Documentation Pending**

withings-api is currently a work in progress. Only support for getting OAuth request and access tokens is supported at this time.

0.0.1

Initial public offereing. OAuth request token and access token support only. No data access yet.

0.0.3

Basic support for measure_getmeas API call

MIT License, see {file:LICENSE}

Thanks to the following software and tools that inspired and made withings-api possible:

• {www.withings.com Withings} - for making awesome hardware and making the data easily accessible

• {github.com/oauth/oauth-ruby OAuth Ruby Gem} - for OAuth plumbing and tools

• {rspec.info/ RSpec} - for unit testing

• {cukes.info/ Cucumber} - for integration and acceptance testing

• {github.com/jnicklas/capybara Capybara} - browser automated acceptance testing

Don’t like withings-api? Patches, changes, and ideas always welcome.

You can also try {github.com/simplificator/simplificator-withings simplificator-withings}.