Class: Telerivet::API

Inherits:
Object
  • Object
show all
Defined in:
lib/telerivet.rb

Constant Summary collapse

@@client_version = 
'1.7.0'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key, api_url = 'https://api.telerivet.com/v1') ⇒ API

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



26
27
28
29
30
31
 
# 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

Instance Attribute Details

#num_requests ⇒ Object (readonly)

Returns the value of attribute num_requests.



10
11
12
 
# File 'lib/telerivet.rb', line 10

def num_requests
  @num_requests
end

Instance Method Details

#cursor(item_cls, path, options) ⇒ Object 



244
245
246
 
# 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) ⇒ Object 



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# 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 ⇒ Object 



240
241
242
 
# File 'lib/telerivet.rb', line 240

def get_base_api_path()
    ""
end

#get_organization_by_id(id) ⇒ Object

Retrieves the Telerivet organization with the given ID.

Arguments:

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

Returns:

Telerivet::Organization



182
183
184
185
 
# 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) ⇒ Object

Retrieves the Telerivet project with the given ID.

Arguments:

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

Returns:

Telerivet::Project



113
114
115
116
 
# 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) ⇒ Object

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



198
199
200
201
 
# 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) ⇒ Object

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



129
130
131
132
 
# 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) ⇒ Object

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)



235
236
237
238
 
# 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) ⇒ Object

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)



166
167
168
169
 
# 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