Step by Step Guide to Building a Fathom API Integration in Ruby

Introduction

Hey there, fellow dev! Ready to dive into the world of Fathom Analytics? If you're looking to integrate this privacy-focused analytics tool into your Ruby project, you're in the right place. We'll walk through building a solid Fathom API integration that'll have you pulling insights like a pro in no time.

Prerequisites

Before we jump in, make sure you've got:

• Ruby 2.7+ installed
• The httparty and dotenv gems
• Your Fathom API key (keep it secret, keep it safe!)

Setting up the project

Let's kick things off by setting up our project:

mkdir fathom_integration && cd fathom_integration
bundle init
echo "gem 'httparty'" >> Gemfile
echo "gem 'dotenv'" >> Gemfile
bundle install

Configuring the Fathom API client

Now, let's create a simple client to handle our Fathom API requests:

# fathom_client.rb
require 'httparty'
require 'dotenv/load'

class FathomClient
  include HTTParty
  base_uri 'https://api.usefathom.com/v1'

  def initialize
    @options = {
      headers: {
        'Authorization' => "Bearer #{ENV['FATHOM_API_KEY']}"
      }
    }
  end

  def get_sites
    self.class.get('/sites', @options)
  end

  # Add more methods for other endpoints
end

Implementing core API functionalities

With our client set up, let's add some methods to fetch data:

# In FathomClient class

def get_analytics(site_id, date_from, date_to)
  self.class.get("/sites/#{site_id}/aggregations", @options.merge(
    query: { date_from: date_from, date_to: date_to }
  ))
end

def get_goals(site_id)
  self.class.get("/sites/#{site_id}/goals", @options)
end

Error handling and rate limiting

Let's add some retry logic and respect those rate limits:

def make_request(method, path, options = {})
  retries = 0
  begin
    response = self.class.send(method, path, options)
    raise 'Rate limited' if response.code == 429
    response
  rescue StandardError => e
    retries += 1
    if retries < 3
      sleep(2**retries)
      retry
    else
      raise e
    end
  end
end

Building a simple CLI interface

Time to make our integration usable from the command line:

# fathom_cli.rb
require_relative 'fathom_client'

client = FathomClient.new

case ARGV[0]
when 'sites'
  puts client.get_sites
when 'analytics'
  puts client.get_analytics(ARGV[1], ARGV[2], ARGV[3])
when 'goals'
  puts client.get_goals(ARGV[1])
else
  puts "Unknown command. Try 'sites', 'analytics', or 'goals'."
end

Testing the integration

Don't forget to test! Here's a quick example using RSpec:

# spec/fathom_client_spec.rb
require 'rspec'
require_relative '../fathom_client'

RSpec.describe FathomClient do
  let(:client) { FathomClient.new }

  it 'fetches sites successfully' do
    VCR.use_cassette('sites') do
      response = client.get_sites
      expect(response.code).to eq(200)
    end
  end

  # Add more tests for other methods
end

Best practices and optimization

To keep things speedy, consider implementing some caching:

def get_sites
  Rails.cache.fetch('fathom_sites', expires_in: 1.hour) do
    make_request(:get, '/sites')
  end
end

Conclusion

And there you have it! You've just built a solid Fathom API integration in Ruby. From setting up the client to handling errors and even throwing in some caching, you're now equipped to pull valuable insights from Fathom Analytics.

Remember, this is just the beginning. There's always room to expand and improve your integration. Why not try adding more endpoints or building a full-fledged Ruby gem?

Keep coding, keep learning, and most importantly, keep having fun with it! If you need more info, don't forget to check out the Fathom API docs. Happy coding!