Step by Step Guide to Building an Acuity Scheduling API Integration in Ruby

Aug 11, 2024 • 6 minute read

Hey there, fellow Ruby enthusiast! Ready to dive into the world of appointment scheduling? Let's get our hands dirty with the Acuity Scheduling API. This guide will walk you through creating a slick integration that'll have you booking appointments like a pro in no time.

Introduction

Acuity Scheduling's API is a powerhouse for managing appointments programmatically. Whether you're building a custom booking system or just want to automate your scheduling, this integration is your ticket to efficiency paradise.

Prerequisites

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

A Ruby environment (2.5+ recommended)
An Acuity Scheduling account with API access
Your favorite code editor

Got all that? Great! Let's roll.

Setting up the project

First things first, let's create a new Ruby project:

mkdir acuity_integration
cd acuity_integration
bundle init

Now, let's add the gems we'll need. Open your Gemfile and add:

gem 'httparty'
gem 'dotenv'

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

Authentication

Acuity uses basic auth, so we'll need your API key and User ID. Create a .env file in your project root:

ACUITY_USER_ID=your_user_id
ACUITY_API_KEY=your_api_key

Now, let's set up our authentication:

require 'dotenv/load'
require 'httparty'

class AcuityClient
  include HTTParty
  base_uri 'https://acuityscheduling.com/api/v1'
  basic_auth ENV['ACUITY_USER_ID'], ENV['ACUITY_API_KEY']
end

Making API requests

Let's create a helper method for our API calls:

def self.api_call(endpoint, method = :get, options = {})
  response = self.send(method, endpoint, options)
  JSON.parse(response.body)
rescue JSON::ParserError
  response.body
end

Core functionality implementation

Now for the fun part! Let's implement some key features:

Fetching appointment types

def self.appointment_types
  api_call('/appointment-types')
end

Retrieving calendar availability

def self.availability(date, appointment_type_id)
  api_call("/availability/dates?month=#{date.strftime('%Y-%m')}&appointmentTypeID=#{appointment_type_id}")
end

Booking an appointment

def self.book_appointment(options)
  api_call('/appointments', :post, body: options)
end

Canceling an appointment

def self.cancel_appointment(appointment_id)
  api_call("/appointments/#{appointment_id}/cancel", :put)
end

Error handling and edge cases

Don't forget to handle those pesky errors:

def self.api_call(endpoint, method = :get, options = {})
  response = self.send(method, endpoint, options)
  
  case response.code
  when 200..299
    JSON.parse(response.body)
  when 429
    raise "Rate limit exceeded. Try again in #{response.headers['Retry-After']} seconds."
  else
    raise "API error: #{response.code} - #{response.message}"
  end
rescue JSON::ParserError
  response.body
end

Testing the integration

Time to make sure everything's working smoothly. Here's a quick test script:

require_relative 'acuity_client'

types = AcuityClient.appointment_types
puts "Available appointment types: #{types}"

availability = AcuityClient.availability(Date.today, types.first['id'])
puts "Availability for #{Date.today}: #{availability}"

# Uncomment to test booking (careful, this will create a real appointment!)
# booking = AcuityClient.book_appointment({
#   appointmentTypeID: types.first['id'],
#   datetime: availability.first['time'],
#   firstName: 'Test',
#   lastName: 'User',
#   email: '[email protected]'
# })
# puts "Booked appointment: #{booking}"

Optimization and best practices

To keep things speedy, consider caching appointment types and implementing webhooks for real-time updates. Your future self will thank you!

Conclusion

And there you have it! You've just built a robust Acuity Scheduling integration in Ruby. From fetching appointment types to booking and canceling, you're now equipped to handle it all. Remember, this is just the beginning – feel free to expand and customize to fit your specific needs.

Resources

Happy coding, and may your calendars always be perfectly scheduled!