Class: MyGengo::API

Inherits:
Object
  • Object
show all
Defined in:
lib/mygengo-ruby/api_handler.rb

Overview

The only real class that ever needs to be instantiated.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(opts) ⇒ API

Creates a new API handler to shuttle calls/jobs/etc over to the myGengo translation API.

Options: opts - A hash containing the api key, the api secret key, the API version (defaults to 1), whether to use the sandbox API, and an optional custom user agent to send.



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/mygengo-ruby/api_handler.rb', line 25

def initialize(opts)
  # Consider this an example of the object you need to pass.
  @opts = {
    :public_key => '',
    :private_key => '',
    :api_version => '1',
    :sandbox => false,
    :user_agent => "myGengo Ruby Library v#{MyGengo::Config::VERSION}",
    :debug => false,
  }.merge(opts)

  # Let's go ahead and separate these out, for clarity...
  @debug = @opts[:debug]
  @api_host = (@opts[:sandbox] == true ? MyGengo::Config::SANDBOX_API_HOST : MyGengo::Config::API_HOST) + "v#{@opts[:api_version]}/"

  # More of a public "check this" kind of object.
  @client_info = {"VERSION" => MyGengo::Config::VERSION}
end

Instance Attribute Details

#api_host ⇒ Object

Returns the value of attribute api_host.



16
17
18
 
# File 'lib/mygengo-ruby/api_handler.rb', line 16

def api_host
  @api_host
end

#client_info ⇒ Object

Returns the value of attribute client_info.



18
19
20
 
# File 'lib/mygengo-ruby/api_handler.rb', line 18

def client_info
  @client_info
end

#debug ⇒ Object

Returns the value of attribute debug.



17
18
19
 
# File 'lib/mygengo-ruby/api_handler.rb', line 17

def debug
  @debug
end

Instance Method Details

#deleteTranslationJob(params = {}) ⇒ Object

Deletes a job.

Options: id - The ID of the job you want to delete.



276
277
278
 
# File 'lib/mygengo-ruby/api_handler.rb', line 276

def deleteTranslationJob(params = {})
  self.send_to_mygengo('translate/job/:id'.gsub(':id', params.delete(:id)), params)
end

#determineTranslationCost(params = {}) ⇒ Object

Mirrors the bulk Translation call, but just returns an estimated cost.



218
219
220
 
# File 'lib/mygengo-ruby/api_handler.rb', line 218

def determineTranslationCost(params = {})
  self.send_to_mygengo('translate/service/quote', params)
end

#get_from_mygengo(endpoint, params = {}) ⇒ Object

The “GET” method; handles requesting basic data sets from myGengo and converting the response to a Ruby hash/object.

Options: endpoint - String/URL to request data from. params - Data necessary for request (keys, etc). Generally taken care of by the requesting instance.



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
 
# File 'lib/mygengo-ruby/api_handler.rb', line 64

def get_from_mygengo(endpoint, params = {})
  # The first part of the object we're going to encode and use in our request to myGengo. The signing process
  # is a little annoying at the moment, so bear with us...
  query = {}
  query["api_key"] = @opts[:public_key]
  query["data"] = params.to_json if !params.empty?
  query["ts"] = Time.now.gmtime.to_i.to_s

  query.merge!("api_sig" => signature_of(query))
  
  endpoint << '?' + query.map { |k, v| "#{k}=#{CGI::escape(v)}" }.join('&')  
  api_url = URI.parse(@api_host + endpoint);

  resp = Net::HTTP.start(api_url.host, api_url.port) do |http|
  puts api_url.request_uri
    http.request(Net::HTTP::Get.new(api_url.request_uri, {
      'Accept' => 'application/json', 
      'User-Agent' => @opts[:user_agent]
    }))
  end
  
  json = JSON.parse(resp.body)

  if json['opstat'] != 'ok'
    raise MyGengo::Exception.new(json['opstat'], json['err']['code'].to_i, json['err']['msg'])
  end

  # Return it if there are no problems, nice...
  json
end

#getAccountBalance(params = {}) ⇒ Object

Returns a Ruby-hash of the balance for the authenticated account. No args required!

Options: None - N/A



162
163
164
 
# File 'lib/mygengo-ruby/api_handler.rb', line 162

def getAccountBalance(params = {})
  self.get_from_mygengo('account/balance', params)
end

#getAccountStats(params = {}) ⇒ Object

Returns a Ruby-hash of the stats for the current account. No arguments required!

Options: None - N/A



154
155
156
 
# File 'lib/mygengo-ruby/api_handler.rb', line 154

def getAccountStats(params = {})
  self.get_from_mygengo('account/stats', params)
end

#getServiceLanguagePairs(params = {}) ⇒ Object

Gets information about currently supported language pairs.

Options: lc_src - Optional language code to filter on.



284
285
286
 
# File 'lib/mygengo-ruby/api_handler.rb', line 284

def getServiceLanguagePairs(params = {})
  self.get_from_mygengo('translate/service/language_pairs', params)
end

#getServiceLanguages(params = {}) ⇒ Object

Pulls down currently supported languages.



289
290
291
 
# File 'lib/mygengo-ruby/api_handler.rb', line 289

def getServiceLanguages(params = {})
  self.get_from_mygengo('translate/service/languages', params)
end

#getTranslationJob(params = {}) ⇒ Object

Given an ID, pulls down information concerning that job from myGengo.

id - The ID of a job to check. pre_mt - Optional, get a machine translation if the human translation is not done.



197
198
199
 
# File 'lib/mygengo-ruby/api_handler.rb', line 197

def getTranslationJob(params = {})
  self.get_from_mygengo('translate/job/:id'.gsub(':id', params.delete(:id)), params)
end

#getTranslationJobBatch(params = {}) ⇒ Object

Pulls a group of jobs that were previously submitted together.

id - Required, the ID of a job that you want the batch/group of.



213
214
215
 
# File 'lib/mygengo-ruby/api_handler.rb', line 213

def getTranslationJobBatch(params = {})
  self.get_from_mygengo('translate/jobs/:id'.gsub(':id', params.delete(:id)), params)
end

#getTranslationJobComments(params = {}) ⇒ Object

Get all comments (the history) from a given job.

Options: id - The ID of the job to get comments for.



235
236
237
 
# File 'lib/mygengo-ruby/api_handler.rb', line 235

def getTranslationJobComments(params = {})
  self.get_from_mygengo('translate/job/:id/comments'.gsub(':id', params.delete(:id)), params)
end

#getTranslationJobFeedback(params = {}) ⇒ Object

Returns the feedback you’ve submitted for a given job.

Options: id - The ID of the translation job you’re retrieving comments from.



243
244
245
 
# File 'lib/mygengo-ruby/api_handler.rb', line 243

def getTranslationJobFeedback(params = {})
  self.get_from_mygengo('translate/job/:id/feedback'.gsub(':id', params.delete(:id)), params)
end

#getTranslationJobPreviewImage(params = {}) ⇒ Object

Returns a preview image for a job.

Options: id - The ID of the job you want a preview image of.



268
269
270
 
# File 'lib/mygengo-ruby/api_handler.rb', line 268

def getTranslationJobPreviewImage(params = {})
  self.get_from_mygengo('translate/job/:id/preview'.gsub(':id', params.delete(:id)), params)
end

#getTranslationJobRevision(params = {}) ⇒ Object

Get a specific revision to a job.

Options: id - The ID of the translation job you’re getting revisions from. rev_id - The ID of the revision you’re looking up.



260
261
262
 
# File 'lib/mygengo-ruby/api_handler.rb', line 260

def getTranslationJobRevision(params = {})
  self.get_from_mygengo('translate/job/:id/revisions/:revision_id'.gsub(':id', params.delete(:id)).gsub(':rev_id', params.delete(:rev_id)), params)
end

#getTranslationJobRevisions(params = {}) ⇒ Object

Gets a list of the revision resources for a job. Revisions are created each time a translator updates the text.

Options: id - The ID of the translation job you’re getting revisions from.



251
252
253
 
# File 'lib/mygengo-ruby/api_handler.rb', line 251

def getTranslationJobRevisions(params = {})
  self.get_from_mygengo('translate/job/:id/revisions'.gsub(':id', params.delete(:id)), params)
end

#getTranslationJobs(params = {}) ⇒ Object

Pulls down a list of recently submitted jobs, allows some filters.

status - Optional. “unpaid”, “available”, “pending”, “reviewable”, “approved”, “rejected”, or “canceled”. timestamp_after - Optional. Epoch timestamp from which to filter submitted jobs. count - Optional. Defaults to 10.



206
207
208
 
# File 'lib/mygengo-ruby/api_handler.rb', line 206

def getTranslationJobs(params = {})
  self.get_from_mygengo('translate/jobs', params)
end

#postTranslationJob(params = {}) ⇒ Object

Posts a translation job over to myGengo, returns a response indicating whether the submission was successful or not. Param list is quite expansive here, pay attention…

Options: job - A job is a hash of data describing what you want translated. See the examples included for more information on what this should be. (type/slug/body_src/lc_src/lc_tgt/tier/auto_approve/comment/callback_url/custom_data)



172
173
174
 
# File 'lib/mygengo-ruby/api_handler.rb', line 172

def postTranslationJob(params = {})
  self.send_to_mygengo('translate/job', params)
end

#postTranslationJobComment(params = {}) ⇒ Object

Post a comment for a translator or myGengo on a job.

Options: id - The ID of the job you’re commenting on. comment - The comment to put on the job.



227
228
229
 
# File 'lib/mygengo-ruby/api_handler.rb', line 227

def postTranslationJobComment(params = {})
  self.send_to_mygengo('translate/job/:id/comment'.gsub(':id', params.delete(:id)), params)
end

#postTranslationJobs(params = {}) ⇒ Object

Much like the above, but takes a hash titled “jobs” that is multiple jobs, each with their own unique key.

Options: jobs - “Jobs” is a hash containing further hashes; each further hash is a job. This is best seen in the example code.



180
181
182
 
# File 'lib/mygengo-ruby/api_handler.rb', line 180

def postTranslationJobs(params = {})
  self.send_to_mygengo('translate/jobs', params)
end

#send_to_mygengo(endpoint, params = {}) ⇒ Object

The “POST” method; handles shuttling up encoded job data to myGengo for translation and such. Somewhat similar to the above methods, but depending on the scenario can get some strange exceptions, so we’re gonna keep them fairly separate for the time being. Consider for a merger down the road…

Options: endpoint - String/URL to post data to. params - Data necessary for request (keys, etc). Generally taken care of by the requesting instance.



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/mygengo-ruby/api_handler.rb', line 103

def send_to_mygengo(endpoint, params = {})
  data = {}

  # ...strip out job data as we need it.
  if !params[:job].nil?
    data[:job] = {:job => params[:job]}
  elsif !params[:jobs].nil?
    data[:jobs] = {:jobs => params[:jobs]}
    data[:process] = params[:process] if !params[:process].nil?
    data[:as_group] = params[:as_group] if !params[:as_group].nil?
  elsif !params[:comment].nil?
    data[:comment] = params[:comment]
  elsif !params[:update].nil?
    # Less confusing for people. ;P
    data[:update] = params[:action]
  end

  # The first part of the object we're going to encode and use in our request to myGengo. The signing process
  # is a little annoying at the moment, so bear with us...
  query = {
    "api_key" => @opts[:public_key],
    "ts" => Time.now.gmtime.to_i.to_s
  }
  query["data"] = data if !data.empty?
  query.merge!('api_sig' => signature_of(query.to_json))
  
  api_url = URI.parse(@api_host + endpoint);

  resp = Net::HTTP.start(api_url.host, api_url.port) do |http|
    req = Net::HTTP::Post.new(api_url.request_uri, {
      'Accept' => 'application/json', 
      'User-Agent' => @opts[:user_agent]
    })
    req.set_form_data query
    http.request(req)
  end
  
  json = JSON.parse(resp.body)

  if json['opstat'] != 'ok'
    raise MyGengo::Exception.new(json['opstat'], json['err']['code'].to_i, json['err']['msg'])
  end

  # Return it if there are no problems, nice...
  json
end

#signature_of(params) ⇒ Object

Creates an HMAC::SHA1 signature, signing the request with the private key.



45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/mygengo-ruby/api_handler.rb', line 45

def signature_of(params)
  if Hash === params
    sorted_keys = params.keys.sort
    params = sorted_keys.zip(params.values_at(*sorted_keys)).map do |k, v|
      "#{k}=#{CGI::escape(v)}"
    end * '&'
  end
  
  # This will be faster, but is more work for an end user to maintain. :(
  #OpenSSL::HMAC.digest(OpenSSL::Digest::Digest.new('sha1'), @opts[:private_key], params)
  HMAC::SHA1.hexdigest @opts[:private_key], params
end

#updateTranslationJob(params = {}) ⇒ Object

Updates an already submitted job.

Options: id - The ID of a job to update. action - A hash describing the update to this job. See the examples for further documentation.



189
190
191
 
# File 'lib/mygengo-ruby/api_handler.rb', line 189

def updateTranslationJob(params = {})   
  self.send_to_mygengo('translate/job/:id'.gsub(':id', params.delete(:id)), params)
end