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



287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/rev-api/api.rb', line 287

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



254
255
256
 
# File 'lib/rev-api/api.rb', line 254

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



262
263
264
265
266
267
268
269
270
 
# File 'lib/rev-api/api.rb', line 262

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 



273
274
275
276
277
278
279
280
 
# File 'lib/rev-api/api.rb', line 273

def verify_post_response(response)
  # see http://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



78
79
80
81
82
 
# File 'lib/rev-api/api.rb', line 78

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).



234
235
236
237
238
239
240
241
242
243
 
# File 'lib/rev-api/api.rb', line 234

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, finished translation or a source file for an order. For transcript and translation 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



115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/rev-api/api.rb', line 115

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 or translation 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



175
176
177
178
 
# File 'lib/rev-api/api.rb', line 175

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, translation, or source file).

Parameters:

  • id (String) —

    attachment id, as returned in info about an order

Returns:



91
92
93
94
95
 
# File 'lib/rev-api/api.rb', line 91

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:



67
68
69
70
71
 
# File 'lib/rev-api/api.rb', line 67

def get_order(number)
  response = @client.get("/orders/#{number}")
  Api.verify_get_response(response)
  Order.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, finished translation or a source file for an order. For transcript and translation 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



145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/rev-api/api.rb', line 145

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).



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

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).



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/rev-api/api.rb', line 205

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