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

Introduction

Hey there, fellow developer! Ready to dive into the world of Copper CRM integration? You're in the right place. Copper's API is a powerful tool that'll let you tap into their CRM functionality, and we're going to build it with Ruby. Buckle up!

Prerequisites

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

• Ruby 2.7+ installed
• The httparty gem (we'll use this for API requests)
• Your Copper API credentials (if you don't have these, hop over to your Copper account and grab them)

Setting Up the Project

Let's get this show on the road. First, create a new Ruby project:

mkdir copper_integration
cd copper_integration
bundle init

Now, add httparty to your Gemfile:

gem 'httparty'

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

Authentication

Copper uses API key authentication. It's straightforward - you'll need to include your API key in the headers of each request. Let's set that up:

require 'httparty'

class CopperAPI
  include HTTParty
  base_uri 'https://api.copper.com/developer_api/v1'

  def initialize(api_key, email)
    @options = {
      headers: {
        'X-PW-AccessToken' => api_key,
        'X-PW-Application' => 'developer_api',
        'X-PW-UserEmail' => email,
        'Content-Type' => 'application/json'
      }
    }
  end
end

Making API Requests

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

def get_people
  self.class.get('/people', @options)
end

Easy peasy, right? This method will fetch all people from your Copper CRM.

CRUD Operations

Let's implement the full CRUD suite:

def create_person(person_data)
  self.class.post('/people', @options.merge(body: person_data.to_json))
end

def get_person(id)
  self.class.get("/people/#{id}", @options)
end

def update_person(id, person_data)
  self.class.put("/people/#{id}", @options.merge(body: person_data.to_json))
end

def delete_person(id)
  self.class.delete("/people/#{id}", @options)
end

Error Handling

Always expect the unexpected! Let's add some error handling:

def handle_response(response)
  case response.code
  when 200..299
    response
  when 401
    raise "Unauthorized: Check your API credentials"
  when 404
    raise "Not Found: The requested resource doesn't exist"
  else
    raise "API Error: #{response.code} - #{response.message}"
  end
end

Wrap your API calls with this method to catch common errors.

Pagination and Filtering

Copper's API uses cursor-based pagination. Here's how to handle it:

def get_all_people(page_size = 200)
  people = []
  page = 1
  loop do
    response = self.class.get('/people', @options.merge(query: { page_size: page_size, page: page }))
    people += response['people']
    break if response['people'].size < page_size
    page += 1
  end
  people
end

Webhooks

Copper supports webhooks for real-time updates. Here's a basic Sinatra server to handle them:

require 'sinatra'
require 'json'

post '/webhook' do
  payload = JSON.parse(request.body.read)
  # Process the webhook payload
  puts "Received webhook: #{payload}"
  status 200
end

Best Practices

• Respect rate limits: Copper allows 600 requests per minute.
• Cache responses when possible to reduce API calls.
• Use background jobs for bulk operations to avoid timeouts.

Testing

Here's a quick RSpec example to get you started with testing:

require 'rspec'
require_relative 'copper_api'

RSpec.describe CopperAPI do
  let(:api) { CopperAPI.new('your_api_key', 'your_email') }

  it 'fetches people successfully' do
    VCR.use_cassette('people') do
      response = api.get_people
      expect(response.code).to eq(200)
      expect(response.parsed_response).to be_an(Array)
    end
  end
end

Conclusion

And there you have it! You've just built a robust Copper API integration in Ruby. Remember, this is just the beginning - there's a whole world of possibilities with the Copper API. Keep exploring, keep coding, and most importantly, have fun with it!

For more details, check out the official Copper API docs. Now go forth and integrate!