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."
Note
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.
Note
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