class Telerivet::API

Attributes

num_requests[R]

Public Class Methods

new(api_key, api_url = 'https://api.telerivet.com/v1') click to toggle source

Initializes a client handle to the Telerivet REST API.

Each API key is associated with a Telerivet user account, and all API actions are performed with that user's permissions. If you want to restrict the permissions of an API client, simply add another user account at <telerivet.com/dashboard/users> with the desired permissions.

Arguments:

- api_key (Your Telerivet API key; see <https://telerivet.com/dashboard/api>)
    * Required
# File lib/telerivet.rb, line 26
def initialize(api_key, api_url = 'https://api.telerivet.com/v1')
    @api_key = api_key
    @api_url = api_url
    @num_requests = 0
    @session = nil
end

Public Instance Methods

cursor(item_cls, path, options) click to toggle source
# File lib/telerivet.rb, line 244
def cursor(item_cls, path, options)
    APICursor.new(self, item_cls, path, options)
end
do_request(method, path, params = nil) click to toggle source
# File lib/telerivet.rb, line 35
def do_request(method, path, params = nil)

    has_post_data = (method == 'POST' || method == 'PUT')

    url = @api_url + path

    if !has_post_data and params != nil && params.length > 0
        url += '?' + URI.encode_www_form(get_url_params(params))
    end

    uri = URI(url)

    if @session == nil
        @session = Net::HTTP.start(uri.host, uri.port,
          :use_ssl => @api_url.start_with?("https://"),
          :ca_file => File.dirname(__FILE__) + '/cacert.pem',
          :read_timeout => 35,
          :open_timeout => 20,
        )
    end

    cls = get_request_class(method)
    request = cls.new(uri.request_uri)

    request['User-Agent'] = "Telerivet Ruby Client/#{@@client_version} Ruby/#{RUBY_VERSION} OS/#{RUBY_PLATFORM}"
    request.basic_auth(@api_key, "")

    if has_post_data
        request.set_content_type("application/json")
        if params != nil
            data = JSON.dump(params)

            if data.length >= 400
                request['Content-Encoding'] = 'gzip'
                data = Zlib::Deflate.new(nil, 31).deflate(data, Zlib::FINISH)
            end

            request.body = data
        end
    end

    @num_requests += 1

    response = @session.request(request)

    begin
        res = JSON.parse(response.body)
    rescue
        raise IOError, "Unexpected response from Telerivet API (HTTP #{response.code}): #{response.body}"
    end

    if res.has_key?("error")
        error = res['error']
        error_code = error['code']

        if error_code == 'invalid_param'
            raise InvalidParameterException, error['message'] #, error['code'], error['param'])
        elsif error_code == 'not_found'
            raise NotFoundException, error['message'] #, error['code']);
        else
            raise APIException, error['message'] #, error['code'])
        end
    else
        return res
    end
end
get_base_api_path() click to toggle source
# File lib/telerivet.rb, line 240
def get_base_api_path()
    ""
end
get_organization_by_id(id) click to toggle source

Retrieves the Telerivet organization with the given ID.

Arguments:

- id
    * ID of the organization -- see <https://telerivet.com/dashboard/api>
    * Required

Returns:

Telerivet::Organization
# File lib/telerivet.rb, line 182
def get_organization_by_id(id)
    require_relative 'telerivet/organization'
    Organization.new(self, self.do_request("GET", get_base_api_path() + "/organizations/#{id}"))
end
get_project_by_id(id) click to toggle source

Retrieves the Telerivet project with the given ID.

Arguments:

- id
    * ID of the project -- see <https://telerivet.com/dashboard/api>
    * Required

Returns:

Telerivet::Project
# File lib/telerivet.rb, line 113
def get_project_by_id(id)
    require_relative 'telerivet/project'
    Project.new(self, self.do_request("GET", get_base_api_path() + "/projects/#{id}"))
end
init_organization_by_id(id) click to toggle source

Initializes the Telerivet organization with the given ID without making an API request.

Arguments:

- id
    * ID of the organization -- see <https://telerivet.com/dashboard/api>
    * Required

Returns:

Telerivet::Organization
# File lib/telerivet.rb, line 198
def init_organization_by_id(id)
    require_relative 'telerivet/organization'
    return Organization.new(self, {'id' => id}, false)
end
init_project_by_id(id) click to toggle source

Initializes the Telerivet project with the given ID without making an API request.

Arguments:

- id
    * ID of the project -- see <https://telerivet.com/dashboard/api>
    * Required

Returns:

Telerivet::Project
# File lib/telerivet.rb, line 129
def init_project_by_id(id)
    require_relative 'telerivet/project'
    return Project.new(self, {'id' => id}, false)
end
query_organizations(options = nil) click to toggle source

Queries organizations accessible to the current user account.

Arguments:

- options (Hash)

  - name
      * Filter organizations by name
      * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
          name[lt], name[lte]

  - sort
      * Sort the results based on a field
      * Allowed values: default, name
      * Default: default

  - sort_dir
      * Sort the results in ascending or descending order
      * Allowed values: asc, desc
      * Default: asc

  - page_size (int)
      * Number of results returned per page (max 500)
      * Default: 50

  - offset (int)
      * Number of items to skip from beginning of result set
      * Default: 0

Returns:

Telerivet::APICursor (of Telerivet::Organization)
# File lib/telerivet.rb, line 235
def query_organizations(options = nil)
    require_relative 'telerivet/organization'
    self.cursor(Organization, get_base_api_path() + "/organizations", options)
end
query_projects(options = nil) click to toggle source

Queries projects accessible to the current user account.

Arguments:

- options (Hash)

  - name
      * Filter projects by name
      * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
          name[lt], name[lte]

  - sort
      * Sort the results based on a field
      * Allowed values: default, name
      * Default: default

  - sort_dir
      * Sort the results in ascending or descending order
      * Allowed values: asc, desc
      * Default: asc

  - page_size (int)
      * Number of results returned per page (max 500)
      * Default: 50

  - offset (int)
      * Number of items to skip from beginning of result set
      * Default: 0

Returns:

Telerivet::APICursor (of Telerivet::Project)
# File lib/telerivet.rb, line 166
def query_projects(options = nil)
    require_relative 'telerivet/project'
    self.cursor(Project, get_base_api_path() + "/projects", options)
end

Private Instance Methods

encode_params_rec(param_name, value, res) click to toggle source
# File lib/telerivet.rb, line 250
def encode_params_rec(param_name, value, res)
    return if value == nil

    if value.kind_of?(Array)
        value.each_index { |i| encode_params_rec("#{param_name}[#{i}]", value[i], res) }
    elsif value.kind_of?(Hash)
        value.each { |k,v| encode_params_rec("#{param_name}[#{k}]", v, res) }
    elsif !!value == value
        res[param_name] = value ? 1 : 0
    else
        res[param_name] = value
    end
end
get_request_class(method) click to toggle source
# File lib/telerivet.rb, line 272
def get_request_class(method)
    case method
    when 'GET' then return Net::HTTP::Get
    when 'POST' then return Net::HTTP::Post
    when 'DELETE' then return Net::HTTP::Delete
    when 'PUT' then return Net::HTTP::Put
    else return nil
    end
end
get_url_params(params) click to toggle source
# File lib/telerivet.rb, line 264
def get_url_params(params)
    res = {}
    if params != nil
        params.each { |key,value| encode_params_rec(key, value, res) }
    end
    return res
end