class TungstenAPI::APICall

This class defines an API call, as needed by the Tungsten Manager API. Up to a ppint, the class is fairly generic, as it defines how to create a URI with three to four segments.

An APICall instance can run a ‘get’ or a ‘post’ call.

Class methods:

Public instance methods:

* initialize (name, prefix, command, help, return_structure = :hash, type = :get)
* description (display_mode ={:text|:hash:json} ) shows the API structure
* make_uri (api_server, service) : creates a well formed URI, ready to submit
* get (api_server, service) : returns the result of a 'get' call
* post (api_server, service) : returns the result of a 'post' operation

Attributes

command[RW]
name[RW]
prefix[RW]
return_structure[RW]
type[RW]

Public Class Methods

dashes() click to toggle source

returns a set of dashes to ptint below the header

# File lib/tungsten/api.rb, line 144
def self.dashes ()
    return sprintf(@@template , '----', '----', '------', '-------' , '----')
end
header() click to toggle source

returns a header for the API call fields

# File lib/tungsten/api.rb, line 137
def self.header ()
    return sprintf(@@template , 'name', 'type', 'prefix', 'command' , 'help')
end
new(name, prefix, command, help, return_structure = :hash, type = :get, ignore_service=false) click to toggle source

Initialize the object.

  • name : how we call the API, even informally. This name is not used operationally

  • prefix: the portion of the call that needs to be inserted before the service name

  • command: what the api call responds to. For some calls, this part can be empty

  • type: either :get or :post

  • return_structure: so far, only :hash is supported

  • help: a brief description of what the API does

# File lib/tungsten/api.rb, line 85
def initialize(name, prefix, command, help, return_structure = :hash, type = :get, ignore_service=false)
    @name = name    
    @prefix = prefix
    @command = command
    @type = type  # type can be :get, :post, :cmd
    @returns = return_structure
    @help = help
    @ignore_service = ignore_service
    # TODO : add expected structure
end
set_api_root(api_root) click to toggle source

Defines the default API root in the URI. Currently it is ‘manager’

# File lib/tungsten/api.rb, line 130
def self.set_api_root(api_root)
    @@api_root = api_root
end
set_return_on_call_fail(return_on_call_fail) click to toggle source

Class method. Defines how we behave in case of call failure By default, we ALWAYS return a :hash. We can also :raise an exception

# File lib/tungsten/api.rb, line 122
def self.set_return_on_call_fail(return_on_call_fail)
    @@return_on_call_fail = return_on_call_fail
end

Public Instance Methods

description(display_mode = :text) click to toggle source

Returns a description of the API call, according to the display_mode:

  • :text (default) is a single line of text according to @@template

  • :hash is a Ruby hash of the API call contents

  • :json is a JSON representation of the above hash

# File lib/tungsten/api.rb, line 168
def description (display_mode = :text)
    if display_mode == :text
        return self.to_s
    end
    if display_mode == :json
        return JSON.generate(self.to_hash)
    elsif display_mode == :hash
        return self.to_hash
    else
        raise SyntaxError, "No suitable display mode selected"
    end
end
evaluate_response(api_server, response) click to toggle source

Used internally by the calls to get and post to determine if the response was successful

# File lib/tungsten/api.rb, line 184
def evaluate_response (api_server, response)
    if response.body
        hash_from_json = JSON.parse(response.body)
    end
    
    unless hash_from_json
      raise "Unable to parse API response from #{api_server}"
    end
    
    if TU.log_cmd_results?()
      TU.debug("Result: #{JSON.pretty_generate(hash_from_json)}")
    end
    
    if hash_from_json && hash_from_json["returnMessage"] && hash_from_json["returnCode"] && hash_from_json["returnCode"] != '200'
        return_object = {
            "httpStatus"    => hash_from_json["returnCode"],
            "message"       => hash_from_json["returnMessage"]
        } 
        if @@return_on_call_fail == :raise
            raise RuntimeError, "There was an error (#{hash_from_json["returnCode"]}) : #{hash_from_json["returnMessage"]}"
        end
        return return_object
    end
 
    if response.code != '200'
        if @@return_on_call_fail == :raise
            raise RuntimeError, "The request returned code #{response.code}"
        else
            return_object = {
                "httpStatus"    => response.code,
                "message"       => "unidentified error with code #{response.code}"
            } 
            return return_object
        end
    end
    return hash_from_json
end
from_hash(hash) click to toggle source
# File lib/tungsten/api.rb, line 96
def from_hash (hash)
    @name = hash[name]
    @prefix = hash[prefix]
    @command = hash[command]
    @type = hash[type]  # type can be :get, :post, :cmd
    @returns = hash[return_structure]
    @help = hash[help]
    self 
end
get(api_server, service) click to toggle source

Runs a ‘get’ call, using a given api_server and service name

# File lib/tungsten/api.rb, line 225
def get(api_server, service)
    api_uri = URI(self.make_uri(api_server,service))
    puts  "GET #{api_uri}" if ENV["SHOW_INTERNALS"]
    TU.debug("GET #{api_uri}")
    response = Net::HTTP.get_response(api_uri)
    return evaluate_response(api_server,response)
end
make_uri(api_server, service) click to toggle source

Creates a well formed URI, ready to be used

# File lib/tungsten/api.rb, line 109
def make_uri(api_server, service)
    if (service && ! @ignore_service)
        return "http://#{api_server}/#{@@api_root}/#{@prefix}/#{service}/#{@command}" 
    else
        return "http://#{api_server}/#{@@api_root}/#{@command}" 
    end
end
post(api_server, service, post_params = {}) click to toggle source

Runs a ‘post’ call, using a given api_server and service name

# File lib/tungsten/api.rb, line 236
def post(api_server, service, post_params = {})
    api_uri = URI(self.make_uri(api_server,service))
    puts  "POST #{api_uri}" if ENV["SHOW_INTERNALS"]
    TU.debug("POST #{api_uri}")
    response = Net::HTTP.post_form(api_uri, post_params)
    return evaluate_response(api_server,response)
end
to_hash() click to toggle source
# File lib/tungsten/api.rb, line 152
def to_hash
    { 
        :name.to_s => @name, 
        :type.to_s => @type, 
        :prefix.to_s => @prefix, 
        :command.to_s => @command, 
        :help.to_s => @help 
    }
end
to_s() click to toggle source
# File lib/tungsten/api.rb, line 148
def to_s
    return sprintf(@@template , @name, @type, @prefix, @command , @help)
end