BookingSync::API

This gem allows Ruby developers to programmatically access https://www.bookingsync.com

Add this line to your application's Gemfile:

gem 'bookingsync-api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install bookingsync-api

Gem assumes that you already have OAuth token for an account.

api = BookingSync::API.new("OAUTH_TOKEN")
rentals = api.rentals # => [BookingSync::API::Resource, BookingSync::API::Resource]
rentals.first.name # => "Small apartment"

All endpoints returning a collection of resources can be paginated. There are three ways to do it.

Specify :per_page and :page params. It's useful when implementing pagination on your site.

api.bookings(per_page: 10, page: 1) => [BookingSync::API::Resource, BookingSync::API::Resource, ...]

Use pagination with a block.

api.bookings(per_page: 10) do |batch|
  # display 10 bookings, will make one HTTP request for each batch
end

Fetch all resources (with multiple requests under the hood) and return one big array.

api.bookings(auto_paginate: true) => [BookingSync::API::Resource, BookingSync::API::Resource, ...]

Some endpoints return additional info about resource in meta section. To fetch it you need to access last response.

api.rentals(updated_since: "2014-01-01 15:43:96 UTC") # => [BookingSync::API::Resource,    BookingSync::API::Resource, ...]
api.last_response.meta # => {"deleted_ids" => [1, 3, 4]}
api.pagination_first_response.meta # => {"deleted_ids" => [1, 3, 4]}

If you need to add custom headers you can use #with_headers method. It accepts hash of headers that should be added to next request and yields client. It resets headers to default ones at the end and returns result of last operation specified inside block.

api.with_headers("x-awesome-header" => "you-bet-i-am") do |adjusted_api_client|
  adjusted_api_client.rentals
end
=> [BookingSync::API::Resource, BookingSync::API::Resource]

Sometimes it's useful to see what data bookingsync-api gem sends and what it receives from the API. By default, gem doesn't log anything. There are two ways to enable logging:

1. Set BOOKINGSYNC_API_DEBUG environment variable to true, when running gem or your app server in development. This will print all logs to STDOUT.

2. Pass your own logger to API client, it can be for example Rails.logger.

api = BookingSync::API.new("OAUTH_TOKEN", logger: Rails.logger)

BookingSync::API exposes instrumentation information that can be consumed by various instrumentation libraries. By default it doesn't send the information anywhere.

To hook instrumentations into ActiveSupport::Notifications, pass the module into the API client initializer:

api = BookingSync::API.new("OAUTH_TOKEN", instrumenter: ActiveSupport::Notifications)

INFO - Logged are only request method and the URL. DEBUG - Logged are request and response headers and bodies.

When using BOOKINGSYNC_API_DEBUG variable, log level is DEBUG.

See gem documentation for more info.

See API documentation.

bundle exec rspec

OR

bundle exec guard

For developing bookingsync-api gem you need OAuth access token. In order to record a cassette, you need to run spec with below environment variables.

ACCESS_TOKEN=abc bundle exec rspec

If you want to change a cassette, you need to delete it first.

There are a few environment variables which comes handy while developing and debugging bookingsync-api gem.

• BOOKINGSYNC_URL - The url of the website, should be. Default https://www.bookingsync.com
• BOOKINGSYNC_VERIFY_SSL - Verify SSL. Default to true.
• BOOKINGSYNC_API_DEBUG - If true, gem will log all request/responses to STDOUT. Default to false.
• ACCESS_TOKEN - OAuth token.

1. Fork it ( http://github.com/BookingSync/bookingsync-api/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request