Class: Rev::Api

Inherits:
Object
  • Object
show all
Defined in:
lib/rev-api/api.rb

Overview

Main point of interaction with API. Wraps common REST operations, returning plain objects. Internally utilizes JSON resource representation.

Constant Summary collapse

PRODUCTION_HOST =

Production host. Used by default for new Rev::Api client

'www.rev.com'
SANDBOX_HOST =

Sandbox domain - pass ‘Rev::Api::SANDBOX_HOST’ as third param into Rev::Api ctor

'api-sandbox.rev.com'

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client_api_key, user_api_key, host = PRODUCTION_HOST) ⇒ HttpClient

Note:

www.rev.com/api/security

Returns client obj.

Parameters:

  • client_api_key (String) —

    secret key specific to each partner that wishes to use the Rev API

  • user_api_key (String) —

    secret key specific to a Rev user, which identifies the user account under whose privileges the requested operation executes

  • host (String) (defaults to: PRODUCTION_HOST) —

    use PRODUCTION_HOST or SANDBOX_HOST. Production is default value



30
31
32
 
# File 'lib/rev-api/api.rb', line 30

def initialize(client_api_key, user_api_key, host = PRODUCTION_HOST)
  @client = HttpClient.new(client_api_key, user_api_key, host)
end

Class Method Details

.handle_error(response) ⇒ Object

Given a response, raises a corresponding Exception. Full response is given for the sake of BadRequest reporting, which usually contains validation errors.

Parameters:

  • response (Response) —

    containing failing status to look for



302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
 
# File 'lib/rev-api/api.rb', line 302

def handle_error(response)
  case response.response
    when Net::HTTPBadRequest
      # Bad request - response contains error code and details. Usually means failed validation
      body = JSON.load response.body.to_s
      msg = "API responded with code #{body['code']}: #{body['message']}"
      msg += " Details: #{body['detail'].to_s}" if body['detail']
      raise BadRequestError.new msg, body['code']
    when Net::HTTPUnauthorized
      raise NotAuthorizedError
    when Net::HTTPForbidden
      raise ForbiddenError
    when Net::HTTPNotFound
      raise NotFoundError
    when Net::HTTPNotAcceptable
      raise NotAcceptableError
    when Net::HTTPServerError
      raise ServerError, "Status code: #{response.code}"
    else
      raise UnknownError
  end
end

.parse(response) ⇒ Hash

Parse given response’s body JSON into Hash, so that it might be easily mapped onto business logic object.

Parameters:

  • response (Response) —

    HTTParty response obj

Returns:

  • (Hash) —

    hash of values parsed from JSON



269
270
271
 
# File 'lib/rev-api/api.rb', line 269

def parse(response)
  JSON.load response.body.to_s
end

.verify_get_response(response) ⇒ Boolean

Raises exception if response is not considered as success

Parameters:

  • response (HTTPParty::Response) —

    HTTParty response obj. Net::HTTPResponse represented by .response

Returns:

  • (Boolean) —

    true if response is considered as successful



277
278
279
280
281
282
283
284
285
 
# File 'lib/rev-api/api.rb', line 277

def verify_get_response(response)
  # HTTP response codes are handled here and propagated up to the caller, since caller should be able
  # to handle all types of errors the same - using exceptions
  unless response.response.instance_of? Net::HTTPOK
    Api.handle_error(response)
  end

  true
end

.verify_post_response(response) ⇒ Object 



288
289
290
291
292
293
294
295
 
# File 'lib/rev-api/api.rb', line 288

def verify_post_response(response)
  # see https://www.rev.com/api/errorhandling
  unless response.response.instance_of?(Net::HTTPCreated) || response.response.instance_of?(Net::HTTPNoContent)
    Api.handle_error(response)
  end

  true
end

Instance Method Details

#cancel_order(number) ⇒ Boolean

Note:

www.rev.com/api/orderscancel

Cancel an order by number. If cancellation is not allowed, Rev::Api::BadRequestError is raised.

Parameters:

  • number (String) —

    order number

Returns:

  • (Boolean) —

    true on success, raised Exception from Rev::Api namespace otherwise



93
94
95
96
97
 
# File 'lib/rev-api/api.rb', line 93

def cancel_order(number)
  data = { :order_num => number }
  response = @client.post("/orders/#{number}/cancel", data)
  Api.verify_post_response(response)
end

#create_input_from_link(url, filename = nil, content_type = nil) ⇒ String

Note:

www.rev.com/api/inputspost

Request creation of a source input based on an external URL which the server will attempt to download.

Parameters:

  • url (String) —

    mandatory, URL where the media can be retrieved. Must be publicly accessible. HTTPS urls are ok as long as the site in question has a valid certificate

  • filename (String, nil) (defaults to: nil) —

    optional, the filename for the media. If not specified, we will determine it from the URL

  • content_type (String, nil) (defaults to: nil) —

    optional, the content type of the media to be retrieved. If not specified, we will try to determine it from the server response

Returns:

  • (String) —

    URI identifying newly uploaded media. This URI can be used to identify the input when constructing a OrderRequest object to submit an order. BadRequestError is raised on failure (.code attr exposes API error code - see InputRequestError).



249
250
251
252
253
254
255
256
257
258
 
# File 'lib/rev-api/api.rb', line 249

def create_input_from_link(url, filename = nil, content_type = nil)
  request = { :url => url }
  request[:filename] = filename unless filename.nil?
  request[:content_type] = content_type unless content_type.nil?

  response = @client.post("/inputs", request.to_json, { 'Content-Type' => 'application/json' })
  Api.verify_post_response(response)

  response.headers['Location']
end

#get_all_orders ⇒ Array of Order

Note:

www.rev.com/api/ordersget

Loads all orders for current client. Works by calling get_orders_page multiple times. Use with caution if your order list might be large.

Returns:

  • (Array of Order) —

    list of orders



50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/rev-api/api.rb', line 50

def get_all_orders
  orders = []
  page = 0
  loop do
    orders_page = self.get_orders_page page
    page += 1
    orders.push *orders_page.orders
    break if (page * orders_page.results_per_page >= orders_page.total_count)
  end
  orders
end

#get_attachment_content(id, mime_type = nil) {|resp| ... } ⇒ Net::HTTP::Response

Get the raw data for the attachment with given id. Download the contents of an attachment. Use this method to download either a finished transcript, or a source file for an order. For transcript attachments, you may request to get the contents in a specific representation, specified via a mime-type.

See Order::Attachment::REPRESENTATIONS hash, which contains symbols for currently supported mime types. The authoritative list is in the API documentation at www.rev.com/api/attachmentsgetcontent

If a block is given, the response is passed to the block directly, to allow progressive reading of the data. In this case, the block must itself check for error responses, using Api.verify_get_response. If no block is given, the full response is returned. In that case, if the response is an error, an appropriate error is raised.

Parameters:

  • id (String) —

    attachment id

  • mime_type (String, nil) (defaults to: nil) —

    mime-type for the desired format in which the content should be retrieved.

Yield Parameters:

  • resp (Net::HTTP::Response) —

    the response, ready to be read

Returns:

  • (Net::HTTP::Response) —

    the response containing raw data



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/rev-api/api.rb', line 130

def get_attachment_content(id, mime_type = nil, &block)
  headers = {}

  unless mime_type.nil?
    headers['Accept'] = mime_type
    headers['Accept-Charset'] = 'utf-8' if mime_type.start_with? 'text/'
  end

  if block_given?
    @client.get_binary("/attachments/#{id}/content", headers, &block)
  else
    response = @client.get_binary("/attachments/#{id}/content", headers)
    Api.verify_get_response(response)
    response
  end
end

#get_attachment_content_as_string(id) ⇒ String

Get the content of the attachment with given id as a string. Use this method to grab the contents of a finished transcript as a string. This method should generally not be used for source attachments, as those are typically binary files like MP3s, which cannot be converted to a string.

May raise Rev::Api::NotAcceptableError if the attachment cannot be converted into a text representation.

Parameters:

  • id (String) —

    attachment id

Returns:

  • (String) —

    the content of the attachment as a string



190
191
192
193
 
# File 'lib/rev-api/api.rb', line 190

def get_attachment_content_as_string(id)
  response = self.get_attachment_content(id, Attachment::REPRESENTATIONS[:txt])
  response.body
end

#get_attachment_metadata(id) ⇒ Attachment

Note:

www.rev.com/api/attachmentsget

Get metadata about an order attachment. Use this method to retrieve information about an order attachment (either transcript, caption or source file).

Parameters:

  • id (String) —

    attachment id, as returned in info about an order

Returns:



106
107
108
109
110
 
# File 'lib/rev-api/api.rb', line 106

def get_attachment_metadata(id)
  response = @client.get("/attachments/#{id}")
  Api.verify_get_response(response)
  Attachment.new(Api.parse(response))
end

#get_order(number) ⇒ Order

Note:

www.rev.com/api/ordersgetone

Returns Order given an order number.

Parameters:

  • number (String) —

    order number, like ‘TCXXXXXXXX’

Returns:



82
83
84
85
86
 
# File 'lib/rev-api/api.rb', line 82

def get_order(number)
  response = @client.get("/orders/#{number}")
  Api.verify_get_response(response)
  Order.new(Api.parse(response))
end

#get_orders_by_client_ref(client_ref, page = 0) ⇒ OrdersListPage

Note:

www.rev.com/api/ordersget

Loads orders whose associated reference ID is the given client_ref

Parameters:

  • client_ref (String, nil) —

    client reference (required)

  • page (Int, nil) (defaults to: 0) —

    0-based page number, defaults to 0

Returns:

Raises:

  • (ArgumentError) —

    client_ref is nil



69
70
71
72
73
74
75
 
# File 'lib/rev-api/api.rb', line 69

def get_orders_by_client_ref(client_ref, page = 0)
  raise ArgumentError if client_ref.nil?

  response = @client.get("/orders?clientRef=#{URI.escape(client_ref)}&page=#{page.to_i}")
  Api.verify_get_response(response)
  OrdersListPage.new(Api.parse(response))
end

#get_orders_page(page = 0) ⇒ OrdersListPage

Note:

www.rev.com/api/ordersget

Loads single page of existing orders for current client

Parameters:

  • page (Int, nil) (defaults to: 0) —

    0-based page number, defaults to 0

Returns:



39
40
41
42
43
 
# File 'lib/rev-api/api.rb', line 39

def get_orders_page(page = 0)
  response = @client.get("/orders?page=#{page.to_i}")
  Api.verify_get_response(response)
  OrdersListPage.new(Api.parse(response))
end

#save_attachment_content(id, path, mime_type = nil) ⇒ String

Get the raw data for the attachment with given id. Download the contents of an attachment and save it into a file. Use this method to download either a finished transcript, or a source file for an order. For transcript attachments, you may request to get the contents in a specific representation, specified via a mime-type.

See Order::Attachment::REPRESENTATIONS hash, which contains symbols for currently supported mime types. The authoritative list is in the API documentation at www.rev.com/api/attachmentsgetcontent

Parameters:

  • id (String) —

    attachment id

  • path (String, nil) —

    path to file into which the content is to be saved.

  • mime_type (String, nil) (defaults to: nil) —

    mime-type for the desired format in which the content should be retrieved.

Returns:

  • (String) —

    filepath content has been saved to. Might raise standard IO exception if file creation files



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/rev-api/api.rb', line 160

def save_attachment_content(id, path, mime_type = nil)
  headers = {}

  unless mime_type.nil?
    headers['Accept'] = mime_type
    headers['Accept-Charset'] = 'utf-8' if mime_type.start_with? 'text/'
  end

  # same simple approach as box-api does for now: return response.body as-is if path for saving is nil
  File.open(path, 'wb') do |file|
    response = @client.get_binary("/attachments/#{id}/content", headers) do |resp|
      resp.read_body do |segment|
        file.write(segment)
      end
    end
    Api.verify_get_response(response)
  end

  # we don't handle IO-related exceptions
  path
end

#submit_order(order_request) ⇒ String

Note:

www.rev.com/api/ordersposttranscription - for full information

Submit a new order using OrderRequest.

Parameters:

  • order_request (OrderRequest) —

    object specifying payment, inputs, options and notification info. inputs must previously be uploaded using upload_input or create_input_from_link

Returns:

  • (String) —

    order number for the new order Raises BadRequestError on failure (.code attr exposes API error code - see OrderRequestError).



203
204
205
206
207
208
209
 
# File 'lib/rev-api/api.rb', line 203

def submit_order(order_request)
  response = @client.post("/orders", order_request.to_json, { 'Content-Type' => 'application/json' })
  Api.verify_post_response(response)

  new_order_uri = response.headers['Location']
  return new_order_uri.split('/')[-1]
end

#upload_input(path, content_type) ⇒ String

Note:

www.rev.com/api/inputspost

Upload given local file directly as source input for order.

Parameters:

  • path (String) —

    mandatory, path to local file (relative or absolute) to upload

  • content_type (String) —

    mandatory, content-type of the file you’re uploading

Returns:

  • (String) —

    URI identifying newly uploaded media. This URI can be used to identify the input when constructing a OrderRequest object to submit an order. BadRequestError is raised on failure (.code attr exposes API error code - see InputRequestError).



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/rev-api/api.rb', line 220

def upload_input(path, content_type)
  filename = Pathname.new(path).basename
  headers = {
    'Content-Disposition' => "attachment; filename=\"#{filename}\"",
    'Content-Type' => content_type
  }

  File.open(path) do |data|
    response = @client.post_binary("/inputs", data, headers)
    Api.verify_post_response(response)

    headers = HTTParty::Response::Headers.new(response.to_hash)
    return headers['Location']
  end
end