Writing a New Strava API Ruby Client

Despite an existing Swagger-compatible API, most of Strava interactions written in Ruby don’t use any auto-generated code and prefer strava-api-v3 (update: this gem was yanked in 2024), a thin client that covers the majority of the Strava API. This is a much cleaner than any swagger-generated mess, but only comes with bare minimum extras. For example, the client can retrieve an activity, but does not have any code to convert a distance from meters to miles or calculate an athlete’s pace. It will also leave you having to refer to the Strava documentation on whether distance is in meters, yards or feet.

That seems reasonable for a thin client, but I’ve already had to copy-paste a ton of code between publishing my runs to github pages and my Strava Slack bot. I considered adding that code to the strava-api-v3 client, but found its implementation gross enough to write a brand new one.

Introducing strava-ruby-client.

Unlike strava-api-v3 provides complete OAuth refresh token flow support, a richer first class interface to Strava models, natively supports pagination and implements more consistent error handling.

The rest of this post is about implementation details.

This is not my first API client rodeo, following the very popular slack-ruby-client and a newer iex-ruby-client, so you can be sure I integrated many of the lessons learned into this work. If you’re building a Ruby client for an API, I strongly encourage you to reuse this as a boilerplate.

Basics

I always start with a README.md, LICENSE.md, CONTRIBUTING.md, CHANGELOG.md and RELEASING.md. Future updates will include UPGRADING.md.

Version

This is very straightforward, but many API clients don’t even include a version, much less announce themselves to servers properly.

module Api
  VERSION = '0.1.0'.freeze
end

We are going to use this in the API’s user agent.

self.user_agent = "Client/#{Api::VERSION}"

And make sure we have a test.

require 'spec_helper'

RSpec.describe Client do
  before do
    Config.reset
  end
  context 'with defaults' do
    let(:client) { Client.new }
    it 'sets user-agent' do
      expect(client.user_agent).to eq Config.user_agent
      expect(client.user_agent).to include Api::VERSION
    end
  end
end

Configuration

API clients tend to want to be configurable globally or directly in a client instance. This is a pretty interesting pattern with the following configuration class.

module Api
  module Config
    extend self

    ATTRIBUTES = %i[
      endpoint
      access_token
      logger
      proxy
      timeout
    ].freeze

    attr_accessor(*Config::ATTRIBUTES)

    def reset
      self.endpoint = 'https://example.com/api'
      self.access_token = nil
      self.logger = Api::Logger.instance
      self.proxy = nil
      self.timeout = 30
    end
  end

  class << self
    def configure
      block_given? ? yield(Config) : Config
    end

    def config
      Config
    end
  end
end

Api::Config.reset

Note that this pattern can be extended deeper, and the configuration can be further nested, as in iex-ruby-client#88.

The client itself.

module Api
  class Client < Strava::Web::Client
    attr_accessor(*Config::ATTRIBUTES)

    def initialize(options = {})
      Config::ATTRIBUTES.each do |key|
        send("#{key}=", options[key] || Api.config.send(key))
      end
    end
  end

  class << self
    def configure
      block_given? ? yield(Config) : Config
    end

    def config
      Config
    end
  end
end

What does this do? It allows global configuration.

Api::Client.configure do |config|
  config.access_token = 'token'
  config.logger = ::Logger.new(STDOUT)
end

And allows local configuration that overrides global configuration.

client = Api::Client.new(access_token: 'token')

HTTP

For HTTP clients I prefer to use Faraday, which allows clients to compose modules in a single pipeline, including Faraday::FlatParamsEncoder to convert input arguments into the HTTP GET query string, FaradayMiddleware::ParseJson to parse JSON in response or Faraday::Response::RaiseError to raise exceptions on HTTP errors. This also allows the caller to swap the HTTP engine in the future, often desired in complex applications that want fewer ways to HTTP.

I breakup the code into Web::Connection and Web::Request, easily gaining global configuration for the much needed proxy or timeout options.

These are mixed into the client class and reuse options from Config::ATTRIBUTES.

class Api
  class Client
    include Web::Connection
    include Web::Request
  end
end

Models

JSON API responses are parsed by Faraday into a Hash, but I prefer first-class objects that can be extended. I like Hashie::Trash, despite being demoniacally possessed.

class Model < Hashie::Trash
  include Hashie::Extensions::IgnoreUndeclared

  property 'id'
  property 'created_at', transform_with: ->(v) { Time.parse(v) }
  property 'widget', transform_with: ->(v) { Models::Widget.new(v) }
  property 'gadgets', transform_with: ->(v) { v.map { |r| Models::Gadget.new(r) } }
end

This allows for first class, strongly typed instance properties and for future extensibility if the API adds fields or a stronger contract with Hashie::Extensions::IgnoreUndeclared deleted.

You can also easily extend the class with additional methods.

class Activity < Hashie::Trash
  property 'type'

  def type_emoji
    case type
    when 'Run' then '🏃'
    when 'Ride' then '🚴'
  end
end

API Calls

A basic API GET call.

#
# Get current user.
#
def current_user(options = {})
  Models::User.new(get('current_user', options))
end

Something with parameters. I choose to use an extensible Hash of options, but YMMV.

#
# Get user by id.
#
# @option options [String] :id
#   User id.
#
def user(options = {})
  throw ArgumentError.new('Required argument :id missing') if options[:id].nil?
  Models::User.new(get("users/#{options[:id]}", options.except(:id)))
end

A collection of objects.

#
# Get users.
#
def users(options = {})
  get('users', options).map do |row|
    Models::User.new(row)
  end
end

Pagination

Clients should help with pagination. I typically roll out a cursor and wrap all collection API calls into it, enabling developers to automatically paginate through results by supplying a block. This can be seen in strava-ruby-client@40f2a0fd.

Famous Last Words

Writing clients is fun. If you are stuck with a crappy client with poor error handling or data modeling, roll your own based on strava-ruby-client in less than a day’s worth of work.

Daniel Doubrovkine

Writing a New Strava API Ruby Client strava | api | ruby