Confrere Ruby API Wrapper

Confrere is an API wrapper for the Confrere API.

Confrere returns a Confrater::Response instead of the response body directly. Confrater::Response exposes the parsed response body and headers.

$ gem install confrater

The Confrere API authenticates using username and password which you can retrieve from your Confrere account.

First, create a one-time use instance of Confrater::Request:

confrere = Confrater::Request.new(username: "your client id", password: "your secret")

Note Only reuse instances of Confrere after terminating a call with a verb, which makes a request. Requests are light weight objects that update an internal path based on your call chain. When you terminate a call chain with a verb, a request instance makes a request and resets the path.

You can set an individual request's timeout and open_timeout like this:

confrere.timeout = 30
confrere.open_timeout = 30

You can read about timeout and open_timeout in the Net::HTTP doc.

Now you can make requests using the resources defined in the Confrere's docs. Resource IDs are specified inline and a CRUD (create, retrieve, update, or delete) verb initiates the request.

You can specify headers, params, and body when calling a CRUD method. For example:

confrere.users.retrieve(headers: {"SomeHeader": "SomeHeaderValue"}, params: {"query_param": "query_param_value"})

Of course, body is only supported on create and update calls. Those map to HTTP POST and PUT verbs respectively.

You can set username, password, api_endpoint, timeout, open_timeout, faraday_adapter, proxy, symbolize_keys, logger, and debug globally:

Confrater::Request.username = "your_client_id"
Confrater::Request.password = "your_secret"
Confrater::Request.timeout = 15
Confrater::Request.open_timeout = 15
Confrater::Request.symbolize_keys = true
Confrater::Request.debug = false

For example, you could set the values above in an initializer file in your Rails app (e.g. your_app/config/initializers/confrere.rb).

Assuming you've set the credentials on Confrere, you can conveniently make API calls on the class itself:

Confrater::Request.users.retrieve

Note Substitute an underscore if a resource name contains a hyphen.

Pass symbolize_keys: true to use symbols (instead of strings) as hash keys in API responses.

confrere = Confrater::Request.new(username: "your_client_id", password: "your_secret", symbolize_keys: true)

Confrere's API documentation is a list of available endpoints.

Pass debug: true to enable debug logging to STDOUT.

confrere = Confrater::Request.new(username: "your_client_id", password: "your_secret", debug: true)

Ruby Logger.new is used by default, but it can be overrided using:

confrere = Confrater::Request.new(username: "your_client_id", password: "your_secret", debug: true, logger: MyLogger.new)

Logger can be also set by globally:

Confrater::Request.logger = MyLogger.new

Fetch all users:

confrere.users.retrieve

Retrieving a specific user looks like:

confrere.users(user_id).retrieve

Add a new appointment:

confrere.appointmets.create(body: {"name": "MakePlans"})

Confrere raises an error when the API returns an error.

Confrater::ConfrereError has the following attributes: title, detail, body, raw_body, status_code. Some or all of these may not be available depending on the nature of the error. For example:

begin
  confrere.users.create(body: body)
rescue Confrater::ConfrereError => e
  puts "Houston, we have a problem: #{e.message} - #{e.raw_body}"
end

You can set an optional proxy url like this (or with an environment variable CONFRERE_PROXY):

confrere.proxy = 'http://your_proxy.com:80'

You can set a different Faraday adapter during initialization:

confrere = Confrater::Request.new(username: "your_client_id", password: "your_secret", faraday_adapter: :net_http)

confrere = Confrater::Request.new(username: "your_client_id", password: "your_secret")

Thanks to everyone who has contributed to Confrere's development.

Based on Gibbon by Amro Mousa.

• Copyright (c) 2010-2017 Espen Antonsen and Amro Mousa. See LICENSE.txt for details.