Step by Step Guide to Building a Cal.com API Integration in Ruby

Introduction

Hey there, fellow developer! Ready to supercharge your scheduling game with Cal.com's API? Let's dive into building a slick Ruby integration that'll have you managing bookings like a pro in no time.

Prerequisites

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

• Ruby 2.7+ (because who doesn't love the latest and greatest?)
• Your trusty Bundler
• A Cal.com API key (if you don't have one, hop over to their site and grab it)

Setting up the project

Let's kick things off:

mkdir calcom_integration
cd calcom_integration
bundle init

Now, crack open that Gemfile and add:

gem 'httparty'
gem 'dotenv'

Run bundle install and you're golden.

Authentication

Create a .env file in your project root:

CALCOM_API_KEY=your_api_key_here

Now, let's create a client:

require 'httparty'
require 'dotenv/load'

class CalComClient
  include HTTParty
  base_uri 'https://api.cal.com/v1'
  
  def initialize
    @options = {
      headers: {
        'Authorization' => "Bearer #{ENV['CALCOM_API_KEY']}",
        'Content-Type' => 'application/json'
      }
    }
  end
end

Basic API Requests

Let's get our feet wet with some basic requests:

def get_user_availability
  self.class.get('/availability', @options)
end

def create_booking(event_type_id, start_time, end_time)
  body = {
    eventTypeId: event_type_id,
    start: start_time,
    end: end_time
  }
  self.class.post('/bookings', @options.merge(body: body.to_json))
end

Implementing Core Functionalities

Now for the fun part - let's implement some core features:

def fetch_available_slots(event_type_id, date)
  response = self.class.get("/availability/#{event_type_id}?date=#{date}", @options)
  response.parsed_response['slots']
end

def update_booking(booking_id, new_start_time, new_end_time)
  body = {
    start: new_start_time,
    end: new_end_time
  }
  self.class.patch("/bookings/#{booking_id}", @options.merge(body: body.to_json))
end

def cancel_booking(booking_id)
  self.class.delete("/bookings/#{booking_id}", @options)
end

Webhooks

If you're feeling adventurous, set up a webhook endpoint:

require 'sinatra'

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

Best Practices

Remember to play nice with the API:

• Implement exponential backoff for rate limiting
• Cache responses when appropriate
• Use background jobs for non-time-sensitive operations

Testing

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

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

  it 'fetches available slots' do
    VCR.use_cassette('available_slots') do
      slots = client.fetch_available_slots('123', '2023-06-01')
      expect(slots).to be_an(Array)
    end
  end
end

Conclusion

And there you have it! You've just built a robust Cal.com API integration in Ruby. With these building blocks, you can create powerful scheduling features in your apps. Remember, the API documentation is your best friend for diving deeper.

Keep coding, keep learning, and most importantly, keep having fun with APIs!