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:
-
set_api_root
: defines which string is the root of the URI (default: ‘manager’) -
set_return_on_call_fail
: defines how we fail when a call does not succeed. You can set either :hash (default) or :raise. When :hash is defined, get and post always return a hash containing ‘message’ and ‘httpStatus’. If :raise is chosen then all call failures will raise an exception -
header : used to display the list of API calls
-
dashes : used to draw dashes below the header. (internally used by TungstenDataserviceManager::list)
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
Public Class Methods
returns a set of dashes to ptint below the header
# File lib/tungsten/api.rb, line 144 def self.dashes () return sprintf(@@template , '----', '----', '------', '-------' , '----') end
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
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
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
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
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
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
# 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
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
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
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
# 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
# File lib/tungsten/api.rb, line 148 def to_s return sprintf(@@template , @name, @type, @prefix, @command , @help) end