lib/oneview-sdk/rest.rb
# (C) Copyright 2016 Hewlett Packard Enterprise Development LP
#
# Licensed under the Apache License, Version 2.0 (the "License");
# You may not use this file except in compliance with the License.
# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software distributed
# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
# CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
# language governing permissions and limitations under the License.
require 'addressable'
require 'uri'
require 'net/http'
require 'openssl'
require 'json'
require 'net/http/post/multipart'
module OneviewSDK
# Contains all of the methods for making API REST calls
module Rest
READ_TIMEOUT = 300 # in seconds, 5 minutes
# Makes a restful API request to OneView
# @param [Symbol] type The rest method/type Options: [:get, :post, :delete, :patch, :put]
# @param [String] path The path for the request. Usually starts with "/rest/"
# @param [Hash] options The options for the request
# @option options [String] :body Hash to be converted into json and set as the request body
# @option options [String] :Content-Type ('application/json') Set to nil or :none to have this option removed
# @option options [Integer] :X-API-Version (client.api_version) API version to use for this request
# @option options [Integer] :auth (client.token) Authentication token to use for this request
# @param [Integer] api_ver The api version to use when interracting with this resource
# @param [Integer] redirect_limit Number of redirects it is allowed to follow
# @raise [OpenSSL::SSL::SSLError] if SSL validation of OneView instance's certificate failed
# @return [NetHTTPResponse] Response object
def rest_api(type, path, options = {}, api_ver = @api_version, redirect_limit = 3)
@logger.debug "Making :#{type} rest call to #{@url}#{path}"
raise InvalidRequest, 'Must specify path' unless path
uri = URI.parse(Addressable::URI.escape(@url + path))
http = build_http_object(uri)
request = build_request(type, uri, options.dup, api_ver)
response = http.request(request)
@logger.debug " Response: Code=#{response.code}. Headers=#{response.to_hash}\n Body=#{response.body}"
if response.class <= Net::HTTPRedirection && redirect_limit > 0 && response['location']
@logger.debug "Redirecting to #{response['location']}"
return rest_api(type, response['location'], options, api_ver, redirect_limit - 1)
end
response
rescue OpenSSL::SSL::SSLError => e
msg = 'SSL verification failed for request. Please either:'
msg += "\n 1. Install the certificate into your system's cert store"
msg += ". Using cert store: #{ENV['SSL_CERT_FILE']}" if ENV['SSL_CERT_FILE']
msg += "\n 2. Run oneview-sdk-ruby cert import #{@url}"
msg += "\n 3. Set the :ssl_enabled option to false for your client (NOT RECOMMENDED)"
@logger.error msg
raise e
end
# Makes a restful GET request to OneView
# @param [String] path The path for the request. Usually starts with "/rest/"
# @param [Hash] options The options for the request
# @option options [String] :Content-Type ('application/json') Set to nil or :none to have this option removed
# @option options [Integer] :X-API-Version (client.api_version) API version to use for this request
# @option options [Integer] :auth (client.token) Authentication token to use for this request
# @param [Integer] api_ver The api version to use when interracting with this resource
# @return [NetHTTPResponse] Response object
def rest_get(path, options = {}, api_ver = @api_version)
rest_api(:get, path, options, api_ver)
end
# Makes a restful POST request to OneView
# @param [String] path The path for the request. Usually starts with "/rest/"
# @param [Hash] options The options for the request
# @option options [String] :body Hash to be converted into json and set as the request body
# @option options [String] :Content-Type ('application/json') Set to nil or :none to have this option removed
# @option options [Integer] :X-API-Version (client.api_version) API version to use for this request
# @option options [Integer] :auth (client.token) Authentication token to use for this request
# @param [Integer] api_ver The api version to use when interracting with this resource
# @return [NetHTTPResponse] Response object
def rest_post(path, options = {}, api_ver = @api_version)
rest_api(:post, path, options, api_ver)
end
# Makes a restful PUT request to OneView
# @param [String] path The path for the request. Usually starts with "/rest/"
# @param [Hash] options The options for the request
# @option options [String] :body Hash to be converted into json and set as the request body
# @option options [String] :Content-Type ('application/json') Set to nil or :none to have this option removed
# @option options [Integer] :X-API-Version (client.api_version) API version to use for this request
# @option options [Integer] :auth (client.token) Authentication token to use for this request
# @param [Integer] api_ver The api version to use when interracting with this resource
# @return [NetHTTPResponse] Response object
def rest_put(path, options = {}, api_ver = @api_version)
rest_api(:put, path, options, api_ver)
end
# Makes a restful PATCH request to OneView
# @param [String] path The path for the request. Usually starts with "/rest/"
# @param [Hash] options The options for the request
# @option options [String] :body Hash to be converted into json and set as the request body
# @option options [String] :Content-Type ('application/json') Set to nil or :none to have this option removed
# @option options [Integer] :X-API-Version (client.api_version) API version to use for this request
# @option options [Integer] :auth (client.token) Authentication token to use for this request
# @param [Integer] api_ver The api version to use when interracting with this resource
# @return [NetHTTPResponse] Response object
def rest_patch(path, options = {}, api_ver = @api_version)
rest_api(:patch, path, options, api_ver)
end
# Makes a restful DELETE request to OneView
# @param [String] path The path for the request. Usually starts with "/rest/"
# @param [Hash] options The options for the request
# @option options [String] :body Hash to be converted into json and set as the request body
# @option options [String] :Content-Type ('application/json') Set to nil or :none to have this option removed
# @option options [Integer] :X-API-Version (client.api_version) API version to use for this request
# @option options [Integer] :auth (client.token) Authentication token to use for this request
# @param [Integer] api_ver The api version to use when interracting with this resource
# @return [NetHTTPResponse] Response object
def rest_delete(path, options = {}, api_ver = @api_version)
rest_api(:delete, path, options, api_ver)
end
# Uploads a file to a specific uri
# @param [String] file_path
# @param [String] path The url path starting with "/"
# @param [Hash] options The options for the request. Default is {}.
# @option options [String] :body Hash to be converted into json and set as the request body
# @option options [String] :header Hash to be converted into json and set as the request header
# @option options [String] :file_name String that defines the new file name
# @param [Integer] timeout The number of seconds to wait for completing the request. Default is 300.
# @return [Hash] The parsed JSON body of response
def upload_file(file_path, path, options = {}, timeout = READ_TIMEOUT)
raise NotFound, "ERROR: File '#{file_path}' not found!" unless File.file?(file_path)
options = Hash[options.map { |k, v| [k.to_s, v] }]
body_params = options['body'] || {}
headers_params = options['header'] || {}
headers = {
'Content-Type' => 'multipart/form-data',
'X-Api-Version' => @api_version.to_s,
'auth' => @token
}
headers.merge!(headers_params)
File.open(file_path) do |file|
name_to_show = options['file_name'] || File.basename(file_path)
body_params['file'] = UploadIO.new(file, 'application/octet-stream', name_to_show)
uri = URI.parse(Addressable::URI.escape(@url + path))
http_request = build_http_object(uri)
http_request.read_timeout = timeout
req = Net::HTTP::Post::Multipart.new(
uri.path,
body_params,
headers
)
http_request.start do |http|
begin
response = http.request(req)
return response_handler(response)
rescue Net::ReadTimeout
raise "The connection was closed because the timeout of #{timeout} seconds has expired."\
'You can specify the timeout in seconds by passing the timeout on the method call.'\
'Interrupted file uploads may result in corrupted file remaining in the appliance.'\
'HPE recommends checking the appliance for corrupted file and removing it.'
end
end
end
end
# Download a file from a specific uri
# @param [String] path The url path starting with "/"
# @param [String] local_drive_path Path to save file downloaded
# @return [Boolean] if file was downloaded
def download_file(path, local_drive_path)
uri = URI.parse(Addressable::URI.escape(@url + path))
http_request = build_http_object(uri)
req = build_request(:get, uri, {}, @api_version.to_s)
http_request.start do |http|
http.request(req) do |res|
response_handler(res) unless res.code.to_i.between?(200, 204)
File.open(local_drive_path, 'wb') do |file|
res.read_body do |segment|
file.write(segment)
end
end
end
end
true
end
RESPONSE_CODE_OK = 200
RESPONSE_CODE_CREATED = 201
RESPONSE_CODE_ACCEPTED = 202
RESPONSE_CODE_NO_CONTENT = 204
RESPONSE_CODE_BAD_REQUEST = 400
RESPONSE_CODE_UNAUTHORIZED = 401
RESPONSE_CODE_NOT_FOUND = 404
# Handles the response from a rest call.
# If an asynchronous task was started, this waits for it to complete.
# @param [HTTPResponse] response HTTP response
# @param [Boolean] wait_on_task Wait on task (or just return task details)
# @raise [OneviewSDK::OneViewError] if the request failed or a task did not complete successfully
# @return [Hash] The parsed JSON body
def response_handler(response, wait_on_task = true)
case response.code.to_i
when RESPONSE_CODE_OK # Synchronous read/query
begin
return JSON.parse(response.body)
rescue JSON::ParserError => e
@logger.warn "Failed to parse JSON response. #{e}"
return response.body
end
when RESPONSE_CODE_CREATED # Synchronous add
JSON.parse(response.body)
when RESPONSE_CODE_ACCEPTED # Asynchronous add, update or delete
return JSON.parse(response.body) unless wait_on_task
@logger.debug "Waiting for task: response.header['location']"
uri = response.header['location'] || JSON.parse(response.body)['uri'] # If task uri is not returned in header
task = wait_for(uri)
return true unless task['associatedResource'] && task['associatedResource']['resourceUri']
resource_data = rest_get(task['associatedResource']['resourceUri'])
JSON.parse(resource_data.body)
when RESPONSE_CODE_NO_CONTENT # Synchronous delete
{}
when RESPONSE_CODE_BAD_REQUEST
BadRequest.raise! "400 BAD REQUEST #{response.body}", response
when RESPONSE_CODE_UNAUTHORIZED
Unauthorized.raise! "401 UNAUTHORIZED #{response.body}", response
when RESPONSE_CODE_NOT_FOUND
NotFound.raise! "404 NOT FOUND #{response.body}", response
else
RequestError.raise! "#{response.code} #{response.body}", response
end
end
private
# Builds a http object using the data given
def build_http_object(uri)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true if uri.scheme == 'https'
if @ssl_enabled
http.cert_store = @cert_store if @cert_store
else http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end
http.read_timeout = @timeout if @timeout # Timeout for a request
http.open_timeout = @timeout if @timeout # Timeout for a connection
http
end
# Builds a request object using the data given
def build_request(type, uri, options, api_ver)
case type.downcase.to_sym
when :get
request = Net::HTTP::Get.new(uri.request_uri)
when :post
request = Net::HTTP::Post.new(uri.request_uri)
when :put
request = Net::HTTP::Put.new(uri.request_uri)
when :patch
request = Net::HTTP::Patch.new(uri.request_uri)
when :delete
request = Net::HTTP::Delete.new(uri.request_uri)
else
raise InvalidRequest, "Invalid rest method: #{type}. Valid methods are: get, post, put, patch, delete"
end
options['X-API-Version'] ||= api_ver
options['auth'] ||= @token
options['Content-Type'] ||= 'application/json'
options.delete('Content-Type') if [:none, 'none', nil].include?(options['Content-Type'])
options.delete('X-API-Version') if [:none, 'none', nil].include?(options['X-API-Version'])
options.delete('auth') if [:none, 'none', nil].include?(options['auth'])
options.each do |key, val|
if key.to_s.downcase == 'body'
request.body = val.to_json rescue val
else
request[key] = val
end
end
@logger.debug " Options: #{options}" # Warning: This may include passwords and tokens
request
end
end
end