Step by Step Guide to Building a SimplyBook.me API Integration in Ruby

Introduction

Hey there, fellow developer! Ready to dive into the world of SimplyBook.me API integration? You're in for a treat. SimplyBook.me's API is a powerful tool that'll let you tap into their booking system, giving your Ruby application some serious scheduling superpowers. Let's get cracking!

Prerequisites

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

• A Ruby environment set up (I know you've probably got this sorted already)
• A SimplyBook.me account with API credentials (if you haven't got this yet, hop over to their site and set it up – it'll only take a minute)

Setting up the project

Alright, let's get our hands dirty:

1. Fire up your terminal and create a new Ruby project:

   mkdir simplybook_integration
   cd simplybook_integration

2. Now, let's add the gems we'll need. Create a Gemfile and add:

   source 'https://rubygems.org'
   
   gem 'httparty'
   gem 'json'

3. Run bundle install and you're good to go!

Authentication

First things first – we need to get that access token:

require 'httparty'
require 'json'

class SimplyBookClient
  BASE_URL = 'https://user-api.simplybook.me'

  def initialize(company_login, api_key)
    @company_login = company_login
    @api_key = api_key
    @token = nil
  end

  def authenticate
    response = HTTParty.post("#{BASE_URL}/login",
      body: {
        company_login: @company_login,
        api_key: @api_key
      }.to_json,
      headers: { 'Content-Type' => 'application/json' }
    )

    @token = JSON.parse(response.body)['token']
  end
end

Pro tip: You'll want to handle token expiration and refreshing in a production app, but let's keep it simple for now.

Basic API requests

Now that we're authenticated, let's make some requests:

def get(endpoint)
  HTTParty.get("#{BASE_URL}/#{endpoint}",
    headers: {
      'Content-Type' => 'application/json',
      'X-Company-Login' => @company_login,
      'X-Token' => @token
    }
  )
end

def post(endpoint, body)
  HTTParty.post("#{BASE_URL}/#{endpoint}",
    body: body.to_json,
    headers: {
      'Content-Type' => 'application/json',
      'X-Company-Login' => @company_login,
      'X-Token' => @token
    }
  )
end

# Similarly for PUT and DELETE...

Key API endpoints

Let's look at some of the most useful endpoints:

def list_services
  get('services')
end

def create_booking(booking_data)
  post('bookings', booking_data)
end

def get_client(client_id)
  get("clients/#{client_id}")
end

Error handling

Always expect the unexpected:

def handle_response(response)
  case response.code
  when 200..299
    JSON.parse(response.body)
  when 401
    authenticate
    # Retry the request
  when 400..499
    raise "Client error: #{response.code} - #{response.body}"
  when 500..599
    raise "Server error: #{response.code} - #{response.body}"
  else
    raise "Unknown error: #{response.code} - #{response.body}"
  end
end

Data parsing and manipulation

SimplyBook.me sends JSON responses. Here's how you might work with them:

def parse_services(response)
  services = JSON.parse(response.body)
  services.map { |service| OpenStruct.new(service) }
end

Building a simple integration

Let's put it all together with a booking system example:

client = SimplyBookClient.new('your_company_login', 'your_api_key')
client.authenticate

services = client.list_services
service = services.first

booking = client.create_booking({
  service_id: service.id,
  client_id: 123,
  date_time: '2023-06-01 14:00:00'
})

puts "Booking created: #{booking['id']}"

Testing

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

RSpec.describe SimplyBookClient do
  let(:client) { SimplyBookClient.new('test_login', 'test_key') }

  it 'authenticates successfully' do
    VCR.use_cassette('authentication') do
      expect { client.authenticate }.not_to raise_error
    end
  end

  # More tests...
end

Best practices

• Be mindful of rate limits – SimplyBook.me has them, so don't go crazy with requests.
• Keep your API credentials safe. Use environment variables or a secure credential store.

Conclusion

And there you have it! You've just built a SimplyBook.me API integration in Ruby. Pretty cool, right? Remember, this is just scratching the surface. There's a whole world of possibilities with this API, so don't be afraid to explore and experiment.

Happy coding, and may your bookings always be on time! 🚀