Strava Ruby Client

Gem Version Build Status

A newer Ruby client for the Strava API v3.

Unlike strava-api-v3 provides a first class interface to Strava models and more consistent error handling.

Table of Contents

Installation

Add to Gemfile.

gem 'strava-ruby-client'

Run bundle install.

Usage

API

Use an access token obtained from My API Application in the Strava UI, the oauth-token tool or the OAuth Workflow in your application.

client = Strava::Api::Client.new(
  access_token: "12345678987654321"
)

Athlete

Get currently logged-in athlete.

client.athlete # => Strava::Models::Athlete

See Strava::Models::Athlete for all available properties.

Athlete Activities

Get currently logged-in athlete activities.

client.athlete_activities # => Array[Strava::Models::Activity]

See Strava::Models::Activity for all available properties.

OAuth

Obtain a redirect URL.

client = Strava::OAuth::Client.new(
  client_id: "12345",
  client_secret: "12345678987654321"
)

redirect_url = client.authorize_url(
  redirect_uri: 'https://example.com/oauth',
  approval_prompt: 'force',
  response_type: 'code',
  scope: 'activity:read_all',
  state: 'magic'
)

Once the user is redirected to your application, perform a token exchange to obtain a refresh and access token.

response = client.oauth_token(code: '1234556789901234567890')

response # => Strava::Models::Token

response.access_token # access token
response.refresh_token # refresh token
response.expires_at # timestamp when the access token expires
response.athlete # => Strava::Models::Athlete

See Strava authentication documentation, Strava::Models::Token and Strava::Models::Athlete for all available properties in the response.

If the access token is expired, refresh it before making any requests. You will get back all new tokens.

response = client.oauth_token(
  refresh_token: '...',
  grant_type: 'refresh_token'
)

response.access_token # new access token
response.refresh_token # new refresh token
response.expires_at # new timestamp when the access token expires

Configuration

Web Client Options

You can configure web client options used in the OAuth and API clients, globally.

Strava::Web::Client.configure do |config|
  config.user_agent = 'Strava Ruby Client/1.0'
end

The following settings are supported.

setting description
user_agent User-agent, defaults to Strava Ruby Client/version.
proxy Optional HTTP proxy.
ca_path Optional SSL certificates path.
ca_file Optional SSL certificates file.
logger Optional Logger instance that logs HTTP requests.
timeout Optional open/read timeout in seconds.
open_timeout Optional connection open timeout in seconds.

API Client Options

The API client inherits web client options and provides additional application configuration. These can be configured globally or for a client instance.

Strava::API.configure do |config|
  config.access_token = "..." # Strava access token
end

client = Strava::API::Client.new(
  access_token: "...",
  user_agent: "..."
)

The following settings are supported.

setting description
access_token Access token to pass in the Authorization header.
endpoint Defaults to https://www.strava.com/api/v3.

OAuth Client Options

The OAuth client inherits web client options and provides additional application configuration. These can be configured globally or for a client instance.

Strava::OAuth.configure do |config|
  config.client_id = "..." # Strava client ID
  config.client_secret = "..." # Strava client secret
end

client = Strava::OAuth::Client.new(
  client_id: "...",
  client_secret: "...",
  user_agent: "..."
)

The following settings are supported.

setting description
client_id Application client ID.
client_secret Application client secret.
endpoint Defaults to https://www.strava.com/oauth.

Errors

All errors that return HTTP codes 400-600 result in either Faraday::Error::ResourceNotFound, Faraday::Error::ConnectionFailed or Strava::Errors::Fault exceptions.

begin
  client.oauth_token(code: 'invalid')
rescue Strava::Errors::Fault => e
  e.message # => Bad Request
  e.errors # => [{ 'code' => 'invalid', 'field' => 'code', 'resource' => 'RequestToken' }]
end

Tools

OAuth Token

Use bin/oauth-token to obtain a token from the command-line.

$ STRAVA_CLIENT_ID=... STRAVA_CLIENT_SECRET=... bundle exec bin/oauth-token.rb

Opening browser at https://www.strava.com/oauth/authorize?...
Copy paste the code from the redirect URL: 1234556789901234567890
token_type: Bearer
refresh_token: 013612374123716234842346234
access_token: 7348562936591928461923619823
expires_at: 2018-11-23 16:25:52 -0500

Contributing

See CONTRIBUTING.

Copyright (c) 2018, Daniel Doubrovkine and Contributors.

This project is licensed under the MIT License.