Class: Telerivet::API

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

Constant Summary collapse

@@client_version = 
'1.1.7'

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



25
26
27
28
29
30
 
# File 'lib/telerivet.rb', line 25

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.



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

def num_requests
  @num_requests
end

Instance Method Details

#cursor(item_cls, path, options) ⇒ Object 



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

def cursor(item_cls, path, options)
    APICursor.new(self, item_cls, path, options)
end

#do_request(method, path, params = nil) ⇒ Object 



34
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
 
# File 'lib/telerivet.rb', line 34

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
            request.body = JSON.dump(params)            
        end
    end
        
    @num_requests += 1

    response = @session.request(request)       
    
    res = JSON.parse(response.body)
    
    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 



159
160
161
 
# File 'lib/telerivet.rb', line 159

def get_base_api_path()
    ""
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



101
102
103
104
 
# File 'lib/telerivet.rb', line 101

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_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



117
118
119
120
 
# File 'lib/telerivet.rb', line 117

def init_project_by_id(id)
    require_relative 'telerivet/project'
    return Project.new(self, {'id' => id}, false)
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 200)
      * Default: 50

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

Returns:

Telerivet::APICursor (of Telerivet::Project)



154
155
156
157
 
# File 'lib/telerivet.rb', line 154

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