Skip to content

Latest commit

 

History

History
168 lines (113 loc) · 4.68 KB

README.md

File metadata and controls

168 lines (113 loc) · 4.68 KB
Raw

Build Status Code Climate

BookingSync::API

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

Installation

Add this line to your application's Gemfile:

gem 'bookingsync-api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install bookingsync-api

Usage

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"

Pagination

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, ...]

Meta information

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]}

Adjust headers dynamically

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]

Logging

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)

Instrumentation

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)

Log levels

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.

Gem documentation

See gem documentation for more info.

API documentation

See API documentation.

Running specs

bundle exec rspec

OR

bundle exec guard

Recording VCR cassettes

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.

Environment variables

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.

Contributing

  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