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

Introduction

Hey there, fellow code wrangler! Ready to dive into the world of Jobber API integration? You're in for a treat. The Jobber API is a powerful tool that'll let you tap into a wealth of field service management data. Whether you're looking to sync client info, manage jobs, or pull financial data, this guide will get you up and running in no time.

Prerequisites

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

• Ruby 2.7+ (because who doesn't love some modern Ruby goodness?)
• Your favorite HTTP client gem (we'll be using faraday in this guide)
• Jobber API credentials (if you don't have these, hop over to Jobber's developer portal and get yourself set up)

Setting up the project

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

mkdir jobber_integration
cd jobber_integration
bundle init

Now, crack open that Gemfile and add:

gem 'faraday'
gem 'dotenv'

Run bundle install, and we're off to the races!

Authentication

Jobber uses OAuth 2.0, so let's get authenticated:

require 'faraday'
require 'dotenv/load'

client_id = ENV['JOBBER_CLIENT_ID']
client_secret = ENV['JOBBER_CLIENT_SECRET']
redirect_uri = 'http://localhost:3000/callback'

auth_url = "https://api.getjobber.com/api/oauth/authorize?client_id=#{client_id}&redirect_uri=#{redirect_uri}&response_type=code"

puts "Visit this URL to authorize: #{auth_url}"

# After authorization, you'll get a code. Use it to get your access token:

code = 'your_authorization_code'

conn = Faraday.new(url: 'https://api.getjobber.com')
response = conn.post('/api/oauth/token') do |req|
  req.body = {
    client_id: client_id,
    client_secret: client_secret,
    code: code,
    grant_type: 'authorization_code',
    redirect_uri: redirect_uri
  }
end

token = JSON.parse(response.body)['access_token']

Making API requests

Now that we're authenticated, let's make a simple GET request:

conn = Faraday.new(
  url: 'https://api.getjobber.com/api',
  headers: { 'Authorization' => "Bearer #{token}" }
)

response = conn.get('/clients')
clients = JSON.parse(response.body)['clients']

Boom! You've just pulled your client list. Pagination? No sweat:

def get_all_clients
  clients = []
  page = 1

  loop do
    response = conn.get('/clients', { page: page })
    new_clients = JSON.parse(response.body)['clients']
    break if new_clients.empty?
    
    clients.concat(new_clients)
    page += 1
  end

  clients
end

CRUD operations

Let's create, update, and delete a client:

# Create
new_client = { client: { name: 'Jane Doe', email: '[email protected]' } }
response = conn.post('/clients', new_client.to_json, 'Content-Type' => 'application/json')

# Update
client_id = JSON.parse(response.body)['client']['id']
updated_client = { client: { name: 'Jane Smith' } }
conn.put("/clients/#{client_id}", updated_client.to_json, 'Content-Type' => 'application/json')

# Delete
conn.delete("/clients/#{client_id}")

Error handling

Always expect the unexpected:

def make_request
  response = yield
  if response.success?
    JSON.parse(response.body)
  else
    handle_error(response)
  end
end

def handle_error(response)
  case response.status
  when 401
    # Handle unauthorized
  when 429
    # Handle rate limit
  else
    # Handle other errors
  end
end

make_request { conn.get('/clients') }

Rate limiting

Jobber's got limits, so let's play nice:

def rate_limited_request
  response = yield
  if response.status == 429
    sleep(response.headers['Retry-After'].to_i)
    rate_limited_request { yield }
  else
    response
  end
end

rate_limited_request { conn.get('/clients') }

Webhooks

Want real-time updates? Set up a webhook endpoint:

require 'sinatra'

post '/webhook' do
  payload = JSON.parse(request.body.read)
  # Process the webhook payload
  status 200
end

Testing

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

RSpec.describe JobberClient do
  it 'fetches clients' do
    stub_request(:get, 'https://api.getjobber.com/api/clients')
      .to_return(body: { clients: [{ id: 1, name: 'Test Client' }] }.to_json)

    clients = JobberClient.new.get_clients
    expect(clients.first['name']).to eq('Test Client')
  end
end

Best practices

A few parting tips:

• Log everything (but scrub sensitive data)
• Cache responses when appropriate
• Keep your API credentials safe (use environment variables!)

Conclusion

And there you have it! You're now armed and dangerous with Jobber API integration skills. Remember, the API docs are your best friend, so keep them close. Happy coding, and may your integrations be ever smooth and your callbacks plentiful!