havenondemand 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bf8402d5a6a70ec39e6addf0955a060ad4efa7fa
-  data.tar.gz: af5d71ee51055958c8e9964dc3d8fe9ec323837f
+  metadata.gz: 4ab5518ee1bc39d91414832b7b7302c3463e44a3
+  data.tar.gz: eea077070860c98331959cde25dd8a57ff7a6643
 SHA512:
-  metadata.gz: 754c02e14e1e72521a319d220d519860faeaabcf7ece763a39f96eb248021b9172ad54791f9d454e684aa314509ec9e2e521a06397116e4e83d8279b5a46e93e
-  data.tar.gz: 740809e9c54e707f4bfe832bbf732eff527e45a11256a4507251859397d6c54f298023288e1e343f85a77131dea50a6a7b8ccdd09d83bbef83af0d0567d939d1
+  metadata.gz: ec8d3d6ccbdfcea63f1ef51b2a15318c81259f271b7e5cedf890d770e2513079fef9b3dd38979055c16cbad6a9db4cddfdbf814cc54cfaa86a2a30cac518a25b
+  data.tar.gz: 68120f53a1e6f514132e02a097d54362623b04649dc9c7c977c77d7aca3c01a936b103a87c8133cf201c442862f15f0fa24e304da246b6345b09428e5f53b88a

data/README.md

@@ -56,145 +56,160 @@ You can find your API key [here](https://www.haveondemand.com/account/api-keys.h
 
 `version` is an optional parameter (defaults to `'v1'`) and can be either `'v1'` or `'v2'`.
 
-###Sending requests
+## Sending requests to the API - POST and GET
+You can send requests to the API with either a POST or GET request, where POST requests are required for uploading files and recommended for larger size queries and GET requests are recommended for smaller size queries.
 
+### POST request
 ```ruby
-r = client.post('analyzesentiment', {:text=>'I like cats'})
+client.get_request(hodApp, params, async, method(:callback))
 ```
-The client's *post* method takes the apipath that you're sending your request to as well as an object containing the parameters you want to send to the api. You do not need to send your apikey each time as the client will handle that automatically
+* `hodApp` is the name of the API you are calling (see this [list]() for available endpoints and our [documentation](https://dev.havenondemand.com/apis) for descriptions of each of the APIs)
+* `params` is a dictionary of parameters passed to the API
+* `async` specifies if you are calling the API asynchronously or synchronously, which is either `true` or `false`, respectively
+* `callback` which is a callback function which is executed when the response from the API is received. Specify 'nil' for returning response.
 
-###Posting files
+### GET request
 ```ruby
-r = client.post('ocrdocument', {:file=>File.new("/path/to/file", 'rb')})
+client.get_request(hodApp, params, async, method(:callback))
 ```
-Sending files is just as easy.
+* `hodApp` is the name of the API you are calling (see this [list]() for available endpoints and our [documentation](https://dev.havenondemand.com/apis) for descriptions of each of the APIs)
+* `params` is a dictionary of parameters passed to the API
+* `async` specifies if you are calling the API asynchronously or synchronously, which is either `true` or `false`, respectively
+* `callback` which is a callback function which is executed when the response from the API is received. Specify 'nil' for returning response.
 
+### POST request for combinations
 ```ruby
-r = client.post('ocrdocument', {:mode=>'photo',:file=>File.new("/path/to/file", 'rb')})
-r = client.post('ocrdocument', {:mode=>'photo',:file=>File.new("/path/to/file", 'rb')})
+client.post_request_combination(hodApp, params, async, method(:callback))
 ```
-Any extra parameters should be added in the same way as regular calls, or in the data parameter.
+* `hodApp` is the name of the combination API you are calling
+* `params` is a dictionary of parameters passed to the API
+* `async` specifies if you are calling the API asynchronously or synchronously, which is either `true` or `false`, respectively
+* `callback` which is a callback function which is executed when the response from the API is received. Specify 'nil' for returning response.
 
-###Parsing the output
 
+### GET request for combinations
 ```ruby
-myjson = r.json()
+client.get_request_combination(hodApp, params, async, method(:callback))
 ```
+* `hodApp` is the name of the combination API you are calling
+* `params` is a dictionary of parameters passed to the API
+* `async` specifies if you are calling the API asynchronously or synchronously, which is either `true` or `false`, respectively
+* `callback` which is a callback function which is executed when the response from the API is received. Specify 'nil' for returning response.
 
-The object returned is a response object from the python [requests library](http://docs.python-requests.org/en/latest/) and can easily be turned to json.
+## Synchronous vs Asynchronous
+Haven OnDemand's API can be called either synchronously or asynchronously. Users are encouraged to call asynchronously if they are POSTing large files that may require a lot of time to process. If not, calling them synchronously should suffice. For more information on the two, see [here](https://dev.havenondemand.com/docs/AsynchronousAPI.htm).
 
-```ruby
-docs = myjson["documents"]
-array.each {|doc| puts doc["title"] }
-```
-
-### Combinations
-
-Haven OnDemand allows to chain two ore more APIs together to create customizable, reusable services. These combinations enable one data input to have unlimited transformations and processing all from a single API call.
+### Synchronous
+To make a synchronous GET request to our Sentiment Analysis API
 
 ```ruby
-data =  { :parameters => { :name => "name_of_input", :value => "value_of_input"} }
-r = client.post_combination('name_of_combination', data)
-puts r.json()
+params = {:text=> 'I love Haven OnDemand!'}
+hodApp = "analyzesentiment"
+response = client.get_request(hodApp, params, false, nil)
 ```
+where the response will be in the `response` variable.
 
-**Note: using local files and publicly accessible URLs is not supported by this wrapper**
-
-To find out more about combinations and how to create one, see [here](https://dev.havenondemand.com/combination/home).
-
-###Indexing
-
-**Creating an index**
+### Asynchronous
+To make an asynchronous POST request to our Sentiment Analysis API
 
 ```ruby
-index = client.createIndex("mytestindex", flavor="explorer")
+params = {:text=> 'I love Haven OnDemand!'}
+hodApp = "analyzesentiment"
+response_async = post_request(hodApp, params, async=true, nil)
+jobID = response_async['jobID']
 ```
+which will return back the job ID of your call. Use the job ID to call the get_job_status() or get_job_result() to get the result.
 
-An Index object can easily be created
+#### Getting the results of an asynchronous request - Status API and Result API
 
-**Fetching indexes/an index**
+##### Status API
+The Status API checks to see the status of your job request. If it is finished processing, it will return the result. If not, it will return you the status of the job.
 
 ```ruby
-index = client.getIndex('myindex')
+client.get_job_status(jobID, method(:callback))
 ```
-The getIndex call will return an hodindex Index object but will not check for existence.
+* `jobID` is the job ID of request returned after performing an asynchronous request
+* `callback` which is a callback function which is executed when the response from the API is received. Specify 'nil' for returning response.
 
+To get the status, or job result if the job is complete
 ```ruby
-indexes = client.listIndexes()
-indexes.fetch('myindex', client.createIndex('myindex'))
+client.get_job_status(jobID, method(:callback))
 ```
 
-Here we first check the list of our indexes and return a newly created index if the index does not already exist
-
-**Deleting an index**
+##### Result API
+The Result API checks the result of your job request. If it is finished processing, it will return the result. If it not, the call the wait until the result is returned or until it times out. **It is recommended to use the Status API over the Result API to avoid time outs**
 
 ```ruby
-index.delete()
-client.deleteIndex('myindex')
+client.get_job_result(jobID, method(:callback))
 ```
-An index can be deleted in two equivalent ways
-
-**Indexing documents**
+* `jobID` is the job ID of request returned after performing an asynchronous request
+* `callback` which is a callback function which is executed when the response from the API is received. Specify 'nil' for returning response.
 
+To get the result
 ```ruby
-doc1 = HODDoc.new({title: "title1", reference: "doc1", content: "my content 1"})
-doc2 = HODDoc.new({title: "title2", reference: "doc2", content: "my content 2"})
-```
-Documents can be created as regular python objects
-
-```
-index.addDoc(doc1)
-index.addDocs([doc1,doc2])
-```
-
-They can be added directly one at a time or in a batch.
-
-```
-for doc in docs:
-  index.pushDoc(doc)
-index.commit()
-```
-
-An alternative to *addDocs* and easy way to keep batch documents is to use the pushDoc method, the index will keep in memory a list of the documents it needs to index.
-
-```
-if index.countDocs()>10:
-  index.commit()
+response = client.get_job_result(jobID, nil)
 ```
 
-It makes it easy to batch together groups of documents.
-
-####Indexing - Connectors
+## Using a callback function
+Most methods allow optional callback functions which are executed when the response of the API is received.
 
 ```ruby
-client = HODClient.new(apikey, version)
-conn = HODConnector.new("mytestconnector", client)
-conn.create(type="web", config = { "url" => "http://www.havenondemand.com" })
-conn.delete()
-```
+def syncCallback(response)
+  response = $parser.parse_payload(response)
+  if response != nil
+    puts response
+  else
+    errors = $parser.get_last_errors()
+    errors.each { |error|
+      eCode = error["error"]
+      if eCode == ErrorCode::QUEUED
+        jobID = error["jobID"]
+        client.get_job_status(jobID, method(:syncCallback))
+      elsif eCode == ErrorCode::IN_PROGRESS
+        jobID = error["jobID"]
+        client.get_job_status(jobID, method(:syncCallback))
+      else
+        puts eCode
+        puts error["detail"]
+        puts error["reason"]
+      end
+    }
+  end
+end
 
+def asyncCallback(response)
+  jobID = $parser.parse_jobid(response)
+  client.get_job_status(jobID, method(:syncCallback))
+end
 
-### Asynchronous request
+params = {:text=> 'I love Haven OnDemand!'}
+hodApp = "analyzesentiment"
+client.post_request(hodApp, params, true, method(:asyncCallback))
+```
 
-For each call the Async parameter can be set to true to send an asynchronous request.
+## POSTing files
+POSTing files is just as easy. Simply include the path to the file you're POSTing in the parameters
 
 ```ruby
-r = client.post('analyzesentiment', {:text => 'I like cats'}, async = true)
-print r.json()
-
-# will return status of call, queued or finished
-puts r.status().json()
-# Will wait until result to return
-puts r.result().json()
+params = {:file=> 'path/to/file.jpg'}
+hodApp = "ocrdocument"
+response = hodClient.post_request(hodApp, params, false, nil)
+puts response
 ```
 
-Same thing for indexing.
+## POSTing files with post_request_combination
+POSTing files to a combination API is slightly different from POSting files to a standalone API.
 
 ```ruby
-r = index.commit(async = true)
+files = [{"file1_input_name"=>"file1name.xxx"},{"file2_input_name"=>"file2name.xxx"}]
+params = {}
+params[:file] = files
+hodApp = "name_of_combination_api"
+response = client.post_request_combination(hodApp, params, false, nil)
 ```
 
-
+## License
+Licensed under the MIT License.
 
 ## Contributing
 We encourage you to contribute to this repo! Please send pull requests with modified and updated code.

data/examples/call_post_request_combination.rb

@@ -0,0 +1,61 @@
+require_relative "../lib/havenondemand.rb"
+
+$client = HODClient.new("YOUR_API_KEY", "v1")
+$parser = HODResponseParser.new()
+
+def syncCallback(response)
+  response = $parser.parse_payload(response)
+  if response != nil
+    puts response
+  else
+    errors = $parser.get_last_errors()
+    errors.each { |error|
+      eCode = error["error"]
+      if eCode == ErrorCode::QUEUED
+        jobID = error["jobID"]
+        sleep(2)
+        $client.get_job_status(jobID, method(:syncCallback))
+      elsif eCode == ErrorCode::IN_PROGRESS
+        jobID = error["jobID"]
+        sleep(5)
+        $client.get_job_status(jobID, method(:syncCallback))
+      else
+        puts eCode
+        puts error["detail"]
+        puts error["reason"]
+      end
+    }
+  end
+end
+
+def asyncCallback(response)
+  jobID = $parser.parse_jobid(response)
+  if jobID != nil
+    $client.get_job_status(jobID, method(:syncCallback))
+  else
+    errors = $parser.get_last_errors()
+    errors.each { |error|
+      eCode = error["error"]
+      puts eCode
+      puts error["detail"]
+      puts error["reason"]
+    }
+  end
+end
+
+# supposed that a combination API takes 2 input files. ! image file for extracting text from image
+# and 1 audio file for extracting text from speech.
+# And the names of the file input are ocrFile and speechFile.
+# And the name of the combination API is "multiplefileinput"
+
+files = [{"ocrFile"=>"review.jpg"},{"speechFile"=>"attendant_test.mp3"}]
+# OR
+=begin
+#file1 = {"ocrFile"=>"review.jpg"}
+#file2 = {"speechFile"=>"attendant_test.mp3"}
+files = []
+files.push(file1)
+files.push(file2)
+=end
+params["file"] = files
+$client.post_request_combination('multiplefileinput', params, true, method(:asyncCallback))

data/examples/callback_async.rb

@@ -0,0 +1,50 @@
+require_relative "../lib/havenondemand.rb"
+
+$client = HODClient.new("YOUR_API_KEY", "v1")
+$parser = HODResponseParser.new()
+
+# call Haven OnDemand APIs using asynchronous mode
+
+def syncCallback(response)
+  response = $parser.parse_payload(response)
+  if response != nil
+    puts response
+  else
+    errors = $parser.get_last_errors()
+    errors.each { |error|
+      eCode = error["error"]
+      if eCode == ErrorCode::QUEUED
+        jobID = error["jobID"]
+        $client.get_job_status(jobID, method(:syncCallback))
+      elsif eCode == ErrorCode::IN_PROGRESS
+        jobID = error["jobID"]
+        $client.get_job_status(jobID, method(:syncCallback))
+      else
+        puts eCode
+        puts error["detail"]
+        puts error["reason"]
+      end
+    }
+  end
+end
+
+def asyncCallback(response)
+  jobID = $parser.parse_jobid(response)
+  if jobID != nil
+    $client.get_job_status(jobID, method(:syncCallback))
+  else
+    errors = $parser.get_last_errors()
+    errors.each { |error|
+      eCode = error["error"]
+      puts eCode
+      puts error["detail"]
+      puts error["reason"]
+    }
+  end
+end
+
+params = {}
+params["url"] = "http://www.cnn.com"
+params["entity_type"] = ['people_eng','places_eng']
+hodApp = 'extractentities'
+$client.post_request(hodApp, params, true, method(:asyncCallback))

data/examples/callback_sync.rb

@@ -0,0 +1,34 @@
+require_relative "../lib/havenondemand.rb"
+
+$client = HODClient.new("YOUR_API_KEY", "v1")
+$parser = HODResponseParser.new()
+
+def syncCallback(response)
+  response = $parser.parse_payload(response)
+  if response != nil
+    puts response
+  else
+    errors = $parser.get_last_errors()
+    errors.each { |error|
+      eCode = error["error"]
+      if eCode == ErrorCode::QUEUED
+        jobID = error["jobID"]
+        $client.get_job_status(jobID, method(:syncCallback))
+      elsif eCode == ErrorCode::IN_PROGRESS
+        jobID = error["jobID"]
+        $client.get_job_status(jobID, method(:syncCallback))
+      else
+        puts eCode
+        puts error["detail"]
+        puts error["reason"]
+      end
+    }
+  end
+end
+
+# call Haven OnDemand APIs using synchronous mode
+params = {}
+params["url"] = "http://www.cnn.com"
+params["entity_type"] = ['people_eng','places_eng']
+hodApp = 'extractentities'
+$client.post_request(hodApp, params, false, method(:syncCallback))

data/examples/post_file.rb

@@ -0,0 +1,52 @@
+require_relative "../lib/havenondemand.rb"
+
+$client = HODClient.new("YOUR_API_KEY", "v1")
+$parser = HODResponseParser.new()
+
+# call Haven OnDemand APIs using asynchronous mode
+
+def syncCallback(response)
+  response = $parser.parse_payload(response)
+  if response != nil
+    puts response
+  else
+    errors = $parser.get_last_errors()
+    errors.each { |error|
+      eCode = error["error"]
+      if eCode == ErrorCode::QUEUED
+        jobID = error["jobID"]
+        sleep(2)
+        $client.get_job_status(jobID, method(:syncCallback))
+      elsif eCode == ErrorCode::IN_PROGRESS
+        jobID = error["jobID"]
+        sleep(5)
+        $client.get_job_status(jobID, method(:syncCallback))
+      else
+        puts eCode
+        puts error["detail"]
+        puts error["reason"]
+      end
+    }
+  end
+end
+
+def asyncCallback(response)
+  jobID = $parser.parse_jobid(response)
+  if jobID != nil
+    $client.get_job_status(jobID, method(:syncCallback))
+  else
+    errors = $parser.get_last_errors()
+    errors.each { |error|
+      eCode = error["error"]
+      puts eCode
+      puts error["detail"]
+      puts error["reason"]
+    }
+  end
+end
+
+params = {}
+params["file"] = "pathto/filename.xxx"
+params["entity_type"] = ['people_eng','places_eng']
+hodApp = 'extractentities'
+$client.post_request(hodApp, params, true, method(:asyncCallback))