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

Introduction

Hey there, fellow developer! Ready to supercharge your proposal process with Proposify's API? Let's dive into building a slick Ruby integration that'll have you managing proposals like a pro in no time.

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 Proposify API credentials (if you don't have these, hop over to your Proposify account settings)

Setting up the project

First things first, let's get our project set up:

mkdir proposify_integration
cd proposify_integration
bundle init

Now, add this to your Gemfile:

gem 'httparty'

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

Authentication

Alright, let's get you authenticated. Create a new file called proposify_client.rb:

require 'httparty'

class ProposifyClient
  include HTTParty
  base_uri 'https://api.proposify.com/v1'

  def initialize(api_key)
    @options = { headers: { 'Authorization' => "Bearer #{api_key}" } }
  end

  # We'll add more methods here soon!
end

Basic API Requests

Now, let's add some methods to make API requests:

def get_proposals
  self.class.get('/proposals', @options)
end

def create_proposal(data)
  self.class.post('/proposals', @options.merge(body: data.to_json))
end

Error handling? We've got you covered:

def handle_response(response)
  case response.code
  when 200...300
    response.parsed_response
  else
    raise "API Error: #{response.code} - #{response.message}"
  end
end

Common Proposify API Operations

Let's add some more useful operations:

def fetch_proposal(id)
  handle_response(self.class.get("/proposals/#{id}", @options))
end

def update_proposal(id, data)
  handle_response(self.class.put("/proposals/#{id}", @options.merge(body: data.to_json)))
end

def send_proposal(id)
  handle_response(self.class.post("/proposals/#{id}/send", @options))
end

Handling Webhooks

Webhooks are crucial for real-time updates. Here's a basic Sinatra app to handle them:

require 'sinatra'
require 'json'

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

Best Practices

Remember to respect rate limits and implement caching where possible. Here's a simple caching example:

def fetch_proposal(id)
  cache_key = "proposal_#{id}"
  cached = read_from_cache(cache_key)
  return cached if cached

  response = handle_response(self.class.get("/proposals/#{id}", @options))
  write_to_cache(cache_key, response)
  response
end

Testing the Integration

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

RSpec.describe ProposifyClient do
  let(:client) { ProposifyClient.new('your_api_key') }

  it 'fetches proposals' do
    VCR.use_cassette('proposals') do
      proposals = client.get_proposals
      expect(proposals).to be_an(Array)
    end
  end
end

Conclusion

And there you have it! You've just built a robust Proposify API integration in Ruby. Remember, this is just the beginning - there's so much more you can do with the API. Keep exploring, keep coding, and most importantly, keep proposing!

For more details, check out the Proposify API documentation. Happy coding!