class Rev::Api

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

Constants

PRODUCTION_HOST

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

SANDBOX_HOST

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

Public Class Methods

new(client_api_key, user_api_key, host = PRODUCTION_HOST) click to toggle source

@note www.rev.com/api/security @param client_api_key [String] secret key specific to each partner that wishes to use the Rev API @param user_api_key [String] secret key specific to a Rev user, which identifies the user account under whose privileges the requested operation executes @param host [String] use {Rev::Api::PRODUCTION_HOST} or {Rev::Api::SANDBOX_HOST}. Production is default value @return [HttpClient] client obj

# 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

Private Class Methods

handle_error(response) click to toggle source

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

@param response [Response] containing failing status to look for

# 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) click to toggle source

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

@param response [Response] HTTParty response obj @return [Hash] hash of values parsed from JSON

# File lib/rev-api/api.rb, line 269
def parse(response)
  JSON.load response.body.to_s
end
verify_get_response(response) click to toggle source

Raises exception if response is not considered as success

@param response [HTTPParty::Response] HTTParty response obj. Net::HTTPResponse represented by .response @return [Boolean] true if response is considered as successful

# 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) click to toggle source

(see verify_get_response)

# 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

Public Instance Methods

cancel_order(number) click to toggle source

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

@note www.rev.com/api/orderscancel @param number [String] order number @return [Boolean] true on success, raised Exception from Rev::Api namespace otherwise

# 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
get_all_orders() click to toggle source

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

@note www.rev.com/api/ordersget @return [Array of Order] list of orders

# 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, &block) click to toggle source

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 {Rev::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.

@param id [String] attachment id @param mime_type [String, nil] mime-type for the desired format in which the content should be retrieved. @yieldparam resp [Net::HTTP::Response] the response, ready to be read @return [Net::HTTP::Response] the response containing raw data

# 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) click to toggle source

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.

@param id [String] attachment id @return [String] the content of the attachment as a string

# 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) click to toggle source

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

@note www.rev.com/api/attachmentsget @param id [String] attachment id, as returned in info about an order @return [Attachment] attachment object

# 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) click to toggle source

Returns Order given an order number.

@note www.rev.com/api/ordersgetone @param number [String] order number, like 'TCXXXXXXXX' @return [Order] order obj

# 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) click to toggle source

Loads orders whose associated reference ID is the given client_ref

@note www.rev.com/api/ordersget @param client_ref [String, nil] client reference (required) @param page [Int, nil] 0-based page number, defaults to 0 @return [OrdersListPage] paged result containing 'orders' list @raise [ArgumentError] client_ref is nil

# 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) click to toggle source

Loads single page of existing orders for current client

@note www.rev.com/api/ordersget @param page [Int, nil] 0-based page number, defaults to 0 @return [OrdersListPage] paged result containing 'orders'

# 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) click to toggle source

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 {Rev::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

@param id [String] attachment id @param path [String, nil] path to file into which the content is to be saved. @param mime_type [String, nil] mime-type for the desired format in which the content should be retrieved. @return [String] filepath content has been saved to. Might raise standard IO exception if file creation files

# 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) click to toggle source

Submit a new order using {Rev::OrderRequest}. @note www.rev.com/api/ordersposttranscription - for full information

@param order_request [OrderRequest] object specifying payment, inputs, options and notification info.

inputs must previously be uploaded using upload_input or create_input_from_link

@return [String] order number for the new order

Raises {Rev::BadRequestError} on failure (.code attr exposes API error code -
see {Rev::OrderRequestError}).
# 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) click to toggle source

Upload given local file directly as source input for order. @note www.rev.com/api/inputspost

@param path [String] mandatory, path to local file (relative or absolute) to upload @param content_type [String] mandatory, content-type of the file you're uploading @return [String] URI identifying newly uploaded media. This URI can be used to identify the input

when constructing a OrderRequest object to submit an order.
{Rev::BadRequestError} is raised on failure (.code attr exposes API error code -
see {Rev::InputRequestError}).
# 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