Step by Step Guide to Building a Setmore Appointments API Integration in Ruby

Introduction

Hey there, fellow developer! Ready to supercharge your app with appointment scheduling capabilities? Look no further than the Setmore Appointments API. In this guide, we'll walk through integrating this powerful tool into your Ruby project. Buckle up, and let's dive in!

Prerequisites

Before we start coding, make sure you've got:

• A Ruby environment set up (2.7+ recommended)
• A Setmore account with API credentials (if you don't have one, sign up at setmore.com)

Setting up the project

Let's kick things off by creating a new Ruby project:

mkdir setmore_integration
cd setmore_integration
bundle init

Now, let's add the necessary gems to our Gemfile:

gem 'httparty'
gem 'dotenv'

Run bundle install, and we're ready to rock!

Authentication

First things first, we need to authenticate with Setmore. Create a .env file in your project root and add your API credentials:

SETMORE_CLIENT_ID=your_client_id
SETMORE_CLIENT_SECRET=your_client_secret

Now, let's create a setmore_client.rb file:

require 'httparty'
require 'dotenv/load'

class SetmoreClient
  include HTTParty
  base_uri 'https://developer.setmore.com/api/v1'

  def initialize
    @access_token = fetch_access_token
  end

  private

  def fetch_access_token
    response = self.class.post('/o/oauth2/token', body: {
      grant_type: 'client_credentials',
      client_id: ENV['SETMORE_CLIENT_ID'],
      client_secret: ENV['SETMORE_CLIENT_SECRET']
    })
    response.parsed_response['access_token']
  end
end

Basic API Requests

Now that we're authenticated, let's add some methods to make API requests:

class SetmoreClient
  # ... previous code ...

  def get(endpoint)
    self.class.get(endpoint, headers: auth_header)
  end

  def post(endpoint, body)
    self.class.post(endpoint, body: body, headers: auth_header)
  end

  private

  def auth_header
    { 'Authorization' => "Bearer #{@access_token}" }
  end
end

Core Functionalities

Let's implement some core appointment functionalities:

class SetmoreClient
  # ... previous code ...

  def available_slots(staff_key, service_key, date)
    get("/bookings/slots?staff_key=#{staff_key}&service_key=#{service_key}&selected_date=#{date}")
  end

  def create_appointment(appointment_data)
    post('/bookings', appointment_data.to_json)
  end

  def update_appointment(appointment_key, updated_data)
    post("/bookings/#{appointment_key}", updated_data.to_json)
  end

  def cancel_appointment(appointment_key)
    post("/bookings/#{appointment_key}/label", { label: 'Canceled' }.to_json)
  end
end

Error Handling

Let's add some basic error handling:

class SetmoreClient
  # ... previous code ...

  def handle_response(response)
    case response.code
    when 200..299
      response.parsed_response
    when 401
      @access_token = fetch_access_token
      retry
    else
      raise "API Error: #{response.code} - #{response.message}"
    end
  end
end

Update your request methods to use this error handling:

def get(endpoint)
  handle_response(self.class.get(endpoint, headers: auth_header))
end

def post(endpoint, body)
  handle_response(self.class.post(endpoint, body: body, headers: auth_header))
end

Data Parsing and Manipulation

Setmore returns JSON responses. Ruby's built-in JSON parser makes it easy to work with this data. Here's a quick example:

slots = client.available_slots('staff123', 'service456', '2023-06-01')
available_times = slots['data']['slots'].map { |slot| slot['start_time'] }

Testing

Don't forget to test your integration! Here's a simple RSpec example:

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

  it 'fetches available slots' do
    slots = client.available_slots('staff123', 'service456', '2023-06-01')
    expect(slots['data']['slots']).to be_an(Array)
  end
end

Best Practices

• Respect Setmore's rate limits to avoid getting your requests blocked.
• Consider implementing caching for frequently accessed data to reduce API calls.
• Always validate and sanitize user input before sending it to the API.

Conclusion

And there you have it! You've just built a solid foundation for integrating Setmore Appointments into your Ruby project. Remember, this is just the beginning - there's so much more you can do with the Setmore API. Keep exploring, keep coding, and most importantly, have fun building amazing things!

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