REST API - Getting Started Using Ruby

Updated

To get started with REST API, a sample script written in Ruby is discussed: rest_api_ruby_sample.zip. The script demonstrates how to interact with the following APIs:

  • POST Login

  • GET Client Properties

  • POST Client Properties

Libraries

The script uses the following libraries:

  • net/http to make API calls.

  • base64 to encode the password.

  • rexml/document to parse XML responses.

Parameters

This script takes the following parameters:

  • server: Name of the machine where the web server is installed.

  • username: Name of the CommCell Console user.

  • password: Password for the user.

Logging On

This part of the script logs on and obtains an authentication token. All API requests must contain an authentication token.

Script

POST: http://<web server host name>:81/SearchSvc/CVWebService.svc/Login

Parameters: None

Body: XML request with the user and a base64 encoded password

Response: XML with an attribute "token"

The libraries are imported, the variables are set, and the password is encoded in base64:

require 'net/http'

require 'base64'

require 'rexml/document'

include REXML

include Net

def fail(msg)

   puts msg

   exit

end

def getResp(res, failureMsg)

   fail(failureMsg) if !res.kind_of? HTTPSuccess

   res.body

end

if ARGV.length < 2

   print "Server name and username are required arguments\n"

   exit

end

server = ARGV[0]

user = ARGV[1]

pwd = ""

pwd = Base64.encode64(ARGV[2]) if ARGV.length > 2

service = "http://#{server}:81/SearchSvc/CVWebService.svc/"

The username and password attributes in the <DM2ContentIndexing_CheckCredentialReq> element are used to pass in the user credentials:

#1. Login

loginReq = "<DM2ContentIndexing_CheckCredentialReq username='#{user}' password='#{pwd}' />"

uri = URI(service + "Login")

req = HTTP::Post.new(uri)

req.body = loginReq

response = HTTP.start(uri.hostname, uri.port) do |http|

   http.request(req)

end

token = ""

respBody = getResp(response, "Login Failed")

doc = Document.new(respBody)

token = XPath.first(doc, ".//@token")

fail("Login Failed") if token == nil

puts "Login Successful"

Getting the Client Properties

This part of the script returns the client properties for a client with a client ID equal to "2."

If the client ID is not known, the GET Client API can be used to retrieve the clientId attribute.

Script

GET: http://<web server host name>:81/SearchSvc/CVWebService.svc/client/{clientId}

Parameters: None

Body: None

Headers: Authtoken (the token received from the login request)

The client ID is set to "2":

#2. Get Client props

clientId = 2

clientPropsUrl = service + "client/#{clientId}"

The token is sent with the request for the client properties. If the request is successful the client name and host name are retrieved from the response:

req = Net::HTTP::Get.new(URI(clientPropsUrl))

req['Authtoken'] = token

response = Net::HTTP.start(uri.hostname, uri.port) {|http|

   http.request(req)

}

getClientResp = getResp(response, "Getting client props failed")

doc = Document.new(getClientResp)

clientName = XPath.first(doc, ".//ActivePhysicalNode/@clientName")

hostName = XPath.first(doc, ".//ActivePhysicalNode/@hostName")

puts "Client Name = #{clientName}, Host Name = #{hostName}"

Posting the Client Properties

This part of the script updates the job priority.

The XML request is hard coded in the sample script, but it can be read from a file to set the appropriate properties.

POST: http://<web server host name>:81/SearchSvc/CVWebService.svc/client/{clientId}

Parameters: None

Body: XML request to set the properties including the client properties to change

Headers: Authtoken (the token received from the login request)

The new job priority is set:

#3. Set client props

newJobPriority = 7

updateClientProps = "<App_SetClientPropertiesRequest><clientProperties><clientProps JobPriority='#{newJobPriority}'></clientProps></clientProperties></App_SetClientPropertiesRequest>"

The request to update the job priority is sent. If the request is successful, the job priority is updated.

req = HTTP::Post.new(URI(clientPropsUrl))

req.body = updateClientProps

req["Authtoken"] = token

response = HTTP.start(uri.hostname, uri.port) do |http|

   http.request(req)

end

setClientResp = getResp(response, "Setting client props failed")

doc = Document.new(getClientResp)

errorCode = XPath.first(doc, ".//response/@errorCode")

if errorCode == 0

   puts "Client properties set Successfully"

else

   puts "Client properties could not be set. Error Code: " + errorCode

end