BookingsyncApiClientV3

Elixir BookingSync (https://www.bookingsync.com) API v3 client. Find more at: http://developers.bookingsync.com

Installation

1. Add :bookingsync_api_client_v3 to your list of dependencies in mix.exs:

def deps do
  [{:bookingsync_api_client_v3, "~> 0.0.1"}]
end

1. Ensure :bookingsync_api_client_v3 is started before your application:

def application do
  [applications: [:bookingsync_api_client_v3]]
end

1. Fetch dependencies:

mix deps.get

Usage

You will need oauth access token to perform any request. If you don't know where you can get one, please visit http://developers.bookingsync.com.

For every request you will need to pass BookingsyncApiClientV3.Data struct. Here's an example how to initialize one

%BookingsyncApiClientV3.Data{
  base_url: "https://bookingsync.dev", # required
  oauth_token: "MY_SECRET_TOKEN", # required
  timeout: 50_000 # not required, 10_000 (10 s) is the default value
}

The result for any request is one of the following options:

1. {:ok, result} tuple indicating success where result is BookingsyncApiClientV3.Result struct.
2. {:error, error_code, error_message} tuple indicating error where error_code is integer standing for HTTP status and error_message is either returned error message deserialized into map if the body was of JSON format or original body if wasn't of JSON format.

BookingsyncApiClientV3.Result contains the following fields:

1. resource containing deserialized body from response. For index action it is list of maps and for show, update and create actions it is map (as only the single record is returned in body).
2. links - map with links from response.
3. meta - map with meta data from response
4. resource_name - name of the resource, e.g. "bookings"

Here some examples of requests:

data = %BookingsyncApiClientV3.Data{base_url: "http://bookingsync.dev", oauth_token: "MY_SECRET_TOKEN"}

# index action, performs autopagination if `next` are available
data |> BookingsyncApiClientV3.Client.get("bookings")

# index action, with query params which will be appended to the url
data |> BookingsyncApiClientV3.Client.get("clients", %{fullname: "Rich Piana"})

# show action, get client with id 96
data |> BookingsyncApiClientV3.Client.get("clients", 96)

# create action, create client with given payload
data |> BookingsyncApiClientV3.Client.post("clients", %{clients: [%{fullname: "Rich Piana"}]})

# update action, update client with id 98 with given payload
data |> BookingsyncApiClientV3.Client.patch("clients", 98, %{clients: [%{fullname: "Updated fullname"}]})

# delete action, destroy booking with id 98
data |> BookingsyncApiClientV3.Client.delete("bookings", 98)

# example of successful request
iex> data |> BookingsyncApiClientV3.Client.get("clients", 96)
{:ok,
 %BookingsyncApiClientV3.Result{links: %{"clients.account" => "http://bookingsync.dev/api/v3/accounts/{clients.account}"},
  meta: %{},
  resource: %{"addresses" => [], "created_at" => "2016-04-01T10:56:49Z",
    "emails" => [], "fullname" => "fullname", "id" => 96,
    "links" => %{"account" => 1}, "notes" => nil, "passport" => nil,
    "phones" => [], "preferred_locale" => nil,
    "updated_at" => "2016-04-01T10:56:49Z"}, resource_name: "clients"}}

# example of request with error
{:error, 401, error_message} = data |> BookingsyncApiClientV3.Client.get("bookings", 1)

iex> error_message == %{"errors" => [%{"code" => "unauthorized"}]}
true

Contributing

• Fork this repo.

• Install dependencies and run tests:

mix test

If you need to record any VCR cassette, you need to provide BOOKINGSYNC_OAUTH_ACCESS_TOKEN ENV variable:

BOOKINGSYNC_OAUTH_ACCESS_TOKEN=MY_SECRET_TOKEN mix test

By default http://bookingsync.dev URL will be used, which can be customized with BOOKINGSYNC_URL ENV variable:

BOOKINGSYNC_OAUTH_ACCESS_TOKEN=MY_SECRET_TOKEN BOOKINGSYNC_URL=https://bookingsync.dev mix test

• Submit pull request.