Class: Telerivet::API

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

Constant Summary collapse

@@client_version = 
'1.8.1'

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 



243
244
245
 
# File 'lib/telerivet.rb', line 243

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
 
# 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://"),
          :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.new error['message'], error['code'], error['param']
        elsif error_code == 'not_found'
            raise NotFoundException.new error['message'], error['code']
        else
            raise APIException.new error['message'], error['code']
        end
    else
        return res
    end
end

#get_base_api_path ⇒ Object 



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

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



181
182
183
184
 
# File 'lib/telerivet.rb', line 181

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



112
113
114
115
 
# File 'lib/telerivet.rb', line 112

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



197
198
199
200
 
# File 'lib/telerivet.rb', line 197

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



128
129
130
131
 
# File 'lib/telerivet.rb', line 128

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)



234
235
236
237
 
# File 'lib/telerivet.rb', line 234

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)



165
166
167
168
 
# File 'lib/telerivet.rb', line 165

def query_projects(options = nil)
    require_relative 'telerivet/project'
    self.cursor(Project, get_base_api_path() + "/projects", options)
end