CobotClient

A client for the Cobot API plus helpers.

Installation

Add this line to your application's Gemfile:

gem 'cobot_client'

And then execute:

$ bundle

Or install it yourself as:

$ gem install cobot_client

Usage

Installing navigation links on Cobot:

You can install links to your app into the navigation on Cobot. When users click the link an iframe pointing to the given iframe_url will be shown.

client = CobotClient::ApiClient.new '<access token>'
CobotClient::NavigationLinkService.new(client, 'co-up').install_links [
  CobotClient::NavigationLink.new(section: 'admin/manage', label: 'My App', iframe_url: 'http://example.com')]

Setting up automatic iframe resizing

When you install your app on Cobot you have to add the following to make sure the iframe on Cobot automatically gets resized according to the height of your page.

This only works for Ruby on Rails >= 3.2. If you are using anything else please take a look at the files involved and set it up manually.

Add this lines to your layout, before the closing </body> tag:

<%= render 'cobot_client/resize_script' %>

This will automatically resize Cobot's iframe whenever a new page is loaded. To manually trigger a resize call window.Cobot.iframeResize().

The default script determine's the iframe height by calling jQuery('body').outerHeight(). To provide your own height you can either pass it to the iframeResize function or you can define a function window.Cobot.iframeHeight.

When you display layers in the iframe that are positioned relative to the window you have to take into account how much the user scrolled down in the parent frame. For this purpose the script provides the property window.Cobot.scrollTop, which returns the no. of pixels the user has scrolled down.

Generating URLs to the Cobot API

There is a module CobotClient::UrlHelper. After you include it you can call cobot_url. Examples:

cobot_url('co-up') # => 'https://co-up.cobot.me/'
cobot_url('co-up', '/api/user') # => 'https://co-up.cobot.me/api/user'
cobot_url('co-up', '/api/user', params: {x: 'y'}) # => 'https://co-up.cobot.me/api/user?x=y'

Calling the API

At the moment there are only a few high-level methods. For more details see the specs.

client = CobotClient::ApiClient.new('<access token>')
client.list_resources('<subdomain>')

For everything else you can use the low-level get/post/put/delete metods:

client.get 'www', '/user'
client.post 'my-subdomain', '/users', {"email": "[email protected]"}

You can also pass a URL instead of subdomain/path:

client.get 'https://www/cobot.me/user'

Error handling

In case of Cobot returning a 4xx or 5xx status code, the ApiClient throws an exception that is a subclass of CobotClient::Exception.

The most common exceptions encountered are CobotClient::NotFound (404), CobotClient::Forbidden (403), CobotClient::UnprocesseableEntity (422) and CobotClient::TooManyRequests (429).

To access the error message contained in the response, rescue the exception and http_body on it:

begin
  client = CobotClient::ApiClient.new('<access token>')
  client.get('www', '/user')
rescue CobotClient::Exception => e
  puts JSON.parse(e.http_body)
end

To access response headers, for example the Retry-After header of a rate-limited request:

begin
  client = CobotClient::ApiClient.new('<access token>')
  client.get('www', '/user')
rescue CobotClient::TooManyRequests => e
  puts e.response.headers[:retry_after].to_i
end

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request