Note: use iod branch for older compatibility syntax.

Official Ruby gem to help with calling Haven OnDemand APIs http://havenondemand.com. Gem is hosted on rubygems.org here.

Haven OnDemand is a set of over 70 APIs for handling all sorts of unstructured data. Here are just some of our APIs' capabilities:

• Speech to text
• OCR
• Text extraction
• Indexing documents
• Smart search
• Language identification
• Concept extraction
• Sentiment analysis
• Web crawlers
• Machine learning

For a full list of all the APIs and to try them out, check out https://www.havenondemand.com/developer/apis

To install from rubygems.org.

gem install havenondemand

To install the latest version from this github repo, use the specific_install gem.

gem install specific_install
gem specific_install https://github.com/HP-Haven-OnDemand/havenondemand-ruby

When using rails and other frameworks with a gem file, include it in it.

gem "havenondemand"

Or, require it directly in your app.

require "havenondemand"

###Initializing the client

client = HODClient.new(apikey, version)

You can find your API key here after signing up.

version is an optional parameter (defaults to 'v1') and can be either 'v1' or 'v2'.

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.

client.get_request(hodApp, params, async, method(:callback))

• hodApp is the name of the API you are calling (see this list for available endpoints and our documentation 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.

client.get_request(hodApp, params, async, method(:callback))

• hodApp is the name of the API you are calling (see this list for available endpoints and our documentation 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.

client.post_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.

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.

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.

To make a synchronous GET request to our Sentiment Analysis API

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.

To make an asynchronous POST request to our Sentiment Analysis API

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.

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.

client.get_job_status(jobID, method(:callback))

• 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

client.get_job_status(jobID, method(:callback))

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

client.get_job_result(jobID, method(:callback))

• 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

response = client.get_job_result(jobID, nil)

Most methods allow optional callback functions which are executed when the response of the API is received.

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

params = {:text=> 'I love Haven OnDemand!'}
hodApp = "analyzesentiment"
client.post_request(hodApp, params, true, method(:asyncCallback))

POSTing files is just as easy. Simply include the path to the file you're POSTing in the parameters

params = {:file=> 'path/to/file.jpg'}
hodApp = "ocrdocument"
response = hodClient.post_request(hodApp, params, false, nil)
puts response

POSTing files to a combination API is slightly different from POSting files to a standalone API.

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)

Licensed under the MIT License.

We encourage you to contribute to this repo! Please send pull requests with modified and updated code.

1. Fork it ( https://github.com/HPE-Haven-OnDemand/havenondemand-ruby/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request