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

Introduction

Hey there, fellow Ruby enthusiast! Ready to dive into the world of FareHarbor API integration? You're in for a treat. This guide will walk you through the process of building a robust integration that'll have you booking tours and activities like a pro. Let's get cracking!

Prerequisites

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

• Ruby 2.7+ installed
• Bundler for managing gems
• Your FareHarbor API credentials (if you don't have these yet, no worries – we'll cover that)

Setting up the project

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

mkdir fareharbor_integration
cd fareharbor_integration
bundle init

Now, open up that shiny new Gemfile and add these gems:

gem 'faraday'
gem 'json'

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

Authentication

Alright, time to get those API keys. Head over to your FareHarbor dashboard and grab your App Key and User Key. Got 'em? Great!

Let's create a simple client to handle our authentication:

require 'faraday'
require 'json'

class FareHarborClient
  BASE_URL = 'https://fareharbor.com/api/external/v1/'

  def initialize(app_key, user_key)
    @app_key = app_key
    @user_key = user_key
  end

  def connection
    @connection ||= Faraday.new(url: BASE_URL) do |faraday|
      faraday.headers['X-FareHarbor-API-App'] = @app_key
      faraday.headers['X-FareHarbor-API-User'] = @user_key
      faraday.adapter Faraday.default_adapter
    end
  end
end

Making API requests

Now that we've got our client set up, let's make some requests:

def get(endpoint)
  response = connection.get(endpoint)
  JSON.parse(response.body)
end

def post(endpoint, payload)
  response = connection.post(endpoint, payload.to_json)
  JSON.parse(response.body)
end

Core API endpoints

Let's implement some key endpoints:

def companies
  get('companies/')
end

def items(company_shortname)
  get("companies/#{company_shortname}/items/")
end

def availabilities(company_shortname, item_id, start_date, end_date)
  get("companies/#{company_shortname}/items/#{item_id}/minimal/availabilities/date-range/#{start_date}/#{end_date}/")
end

Booking process

Time to book an adventure! Here's a simple booking method:

def create_booking(company_shortname, availability_id, customer_data)
  payload = {
    voucher_number: SecureRandom.hex(8),
    contact: customer_data,
    customers: [customer_data]
  }
  post("companies/#{company_shortname}/availabilities/#{availability_id}/bookings/", payload)
end

Error handling and edge cases

Let's add some error handling to our client:

class FareHarborError < StandardError; end

def handle_response(response)
  case response.status
  when 200..299
    JSON.parse(response.body)
  else
    raise FareHarborError, "API request failed: #{response.status} - #{response.body}"
  end
end

Update your get and post methods to use handle_response.

Testing the integration

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

RSpec.describe FareHarborClient do
  let(:client) { FareHarborClient.new('app_key', 'user_key') }

  it 'fetches companies' do
    VCR.use_cassette('companies') do
      companies = client.companies
      expect(companies).to be_an(Array)
      expect(companies.first).to have_key('shortname')
    end
  end
end

Performance optimization

To keep things speedy, consider caching responses:

def companies
  Rails.cache.fetch('fareharbor_companies', expires_in: 1.day) do
    get('companies/')
  end
end

Deployment considerations

When deploying, remember to:

1. Set your API keys as environment variables
2. Keep an eye on API versioning
3. Implement proper logging for production debugging

Conclusion

And there you have it! You've just built a solid FareHarbor API integration in Ruby. From authentication to booking, you're now equipped to handle it all. Remember, the API docs are your friend, so don't hesitate to dive deeper for more advanced features.

Happy coding, and may your bookings always be successful! 🚀