riverbed cascade profiler common rest api v1€¦ · overview overview the documentation pages in...

Riverbed Cascade Profiler Common REST APIv10Copyright copy Riverbed Technology Inc 2018

Created Sep 23 2020 at 0509 PM

Overview

OverviewThe documentation pages in this section describe the RESTful APIs included with Cascade Profiler and Cascade Expressproducts It is assumed that the reader has practical knowledge of RESTful APIs so the documentation does not go intodetail about what REST is and how to use it Instead the documentation focuses on what data can be accessed andhow to access it

The primary focus of the current version of the API is on providing access to common data The following informationcan be accessed via the API

System information (serial number model etc)Information and resources for authenticating (login logout oauth 20 etc)

Details about REST resources can be found in the Resources section

SSLAll communication to the profiler is SSL encrypted on Port 443 There is no support for access to the profiler on thestandard HTTP port 80

CiphersThe ciphers supported by the Profiler may change depending on security setting (eg FIPS mode) Any client wheninitiating a request must include one or more ciphers available in the Profilers configured list Otherwise the client willreceive an SSL error indicating that there is no cipher overlap and will be unable to connect

CertificateThe profiler by default uses a self-signed certificate for SSL communication The client should be able to handle this bypermitting self-signed certificates

ExamplesUsing the curl command line client to request the services resource on a non-FIPS box The -k switch is used to allowthe self-signed certificate and a cipher suite (SSL v3) is provided

curl -k -3 httpshostname443apicommon10services

Using the curl command line client to request the services resource on a FIPS box An explicit cipher is selected

curl --ciphers rsa_aes_256_sha -k httpshostname443apicommon10services

Known IssuesSome clients such as Curl (both as a library and a command line executable) do not support both an explicit cipherlist and a cipher suite The following command will fail on a FIPS Profiler

curl --ciphers rsa_aes_256_sha -3 -k httpshostname443apicommon10services

This is because the cipher suite (-3) overrides the --ciphers argument Clients with this issue will receive a no cipheroverlap error even if they have explicitly provided a cipher that is known to be FIPS compliant

BASIC AuthenticationFor BASIC authentication the request header Authorization must be set to a base64-encoded string ofusernamepassword

If the Authorization header is not provided the WWW-Authenticate response header is returned Basicauthentication has a built-in support in various tools Refer to the coding examples

Example of client request to protected resource using Basic Authentication

POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Basic YWRtaW46YWRtaW4=

Server response

HTTP11 204 OK

Sample PHP script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication

ltphp

define(HOST 127001) IP address of Profilerdefine(BASIC_AUTH adminadmin)

HTTP GETfunction do_GET($url amp$info) $curl = curl_init() curl_setopt($curl CURLOPT_URL $url) curl_setopt($curl CURLOPT_HTTPAUTH CURLAUTH_BASIC ) curl_setopt($curl CURLOPT_USERPWD BASIC_AUTH) curl_setopt($curl CURLOPT_SSLVERSION3) curl_setopt($curl CURLOPT_SSL_VERIFYPEER FALSE) curl_setopt($curl CURLOPT_SSL_VERIFYHOST 2) curl_setopt($curl CURLOPT_HEADER true) curl_setopt($curl CURLOPT_RETURNTRANSFER true) curl_setopt($curl CURLOPT_HTTPHEADER array(Accept applicationjson)) curl_setopt($curl CURLOPT_HTTPGET true) $output = curl_exec($curl) $info = curl_getinfo($curl) curl_close($curl)

$headers = substr($output 0 $info[header_size]) $headers = explode(n $headers) $info[headers] = $headers $body = substr($output $info[header_size]) return $body

Ping to test basic authentication$url = https HOST apiprofiler10pingecho GET $urln

$info = array()$output = do_GET($url $info)

if ($info[http_code] == 204) echo Ping is successfuln else echo Ping failedn echo $output

gt

Sample Python script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication

from urlparse import urlparseimport base64import loggingimport httplibimport jsonimport timeimport sys

HOST = 127001BASIC_AUTH = adminadmin

Lib functions

def do_GET(url) HTTP GET

conn = httplibHTTPSConnection(HOST 443)

headers = Authorization Basic s base64b64encode(BASIC_AUTH) Content-Length 0 Accept applicationjson

connrequest(GET url body= headers=headers)

res = conngetresponse()

info = status resstatus headers resgetheaders()

data = resread() connclose() return data info

Ping to test basic authentication

url = httpssapiprofiler10ping HOSTprint GET s url

output info = do_GET(url)

if (info[status] == 204) print Ping is successfulelse print Ping failed print output

Sample Perl script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication

usrbinperluse strictuse warnings

use LWPUserAgentuse HTTPRequestuse ListMoreUtils qw(firstidx)use JSON qw( encode_json decode_json )

use constant HOST =gt 127001use constant LOGIN =gt adminuse constant PASSWORD =gt admin

our $ua = LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)

our $API_BASE = https127001

sub _request($) my $req = shift

$req-gtheader(Accept =gt applicationjson) $req-gtauthorization_basic(LOGIN PASSWORD)

my $res = $ua-gtrequest($req)

return code =gt $res-gtcode status =gt $res-gtstatus_line headers =gt $res-gtheaders() data =gt $res-gtcontent

sub GET($) my $req = HTTPRequest-gtnew(GET =gt $API_BASE shift) return _request($req)


print GET apiprofiler10pingnmy $response = GET(apiprofiler10ping)

if ($response-gtcode == 204) print Ping is successfuln else print Ping failedn print $response-gtdata

Sample NetC script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication

using Systemusing SystemCollectionsGenericusing SystemNetusing SystemTextusing SystemIOusing SystemNetSecurityusing SystemSecurityCryptographyX509Certificates

namespace CascadeRestClient class Program static string BASIC_AUTH = adminadmin

callback used to validate the self-gen certificate in an SSL conversation private static bool ValidateRemoteCertificate(object sender X509Certificate cert X509Chain chain SslPolicyErrors policyErrors) return true X509Certificate2 certv2 = new X509Certificate2(cert) if (certv2GetNameInfo(X509NameTypeSimpleNametrue) == wwwriverbedcom) return true

return false

private static string Base64Encode(string toEncode) byte[] toEncodeAsBytes = SystemTextASCIIEncodingASCIIGetBytes(toEncode) return SystemConvertToBase64String(toEncodeAsBytes)

static void Main(string[] args) if (argsLength == 0 || stringIsNullOrWhiteSpace(args[0])) ConsoleWriteLine(Usage CascadeRestClient hostname) return try Code to allow run with self-signed certificates validate cert by calling a function ServicePointManagerServerCertificateValidationCallback += new RemoteCertificateValidationCallback(ValidateRemoteCertificate)

Starting to run rest string rootUrl = https + args[0] string requestUrl = rootUrl + apiprofiler10ping

Ping to test beaic authentication ConsoleWriteLine(GET + requestUrl)

Post to run the report HttpWebRequest request = WebRequestCreate(requestUrl) as HttpWebRequest requestHeadersAdd(Authorization Basic + Base64Encode(BASIC_AUTH)) requestContentType = applicationjson requestMethod = WebRequestMethodsHttpGet requestContentLength = 0 using (var response = requestGetResponse() as HttpWebResponse) if (responseStatusCode == HttpStatusCodeNoContent) ConsoleWriteLine(Ping is successful) else ConsoleWriteLine(Ping failed) using (Stream stream = responseGetResponseStream()) using (StreamReader reader = new StreamReader(stream EncodingUTF8)) String responseString = readerReadToEnd() ConsoleWriteLine(responseString)

catch (Exception e) ConsoleWriteLine(eMessage)

Sample CURL command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication

curl --user usernamepassword httpshostapiprofiler10ping -k

Sample WGET command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication

wget --http-user username --http-password password httpshostapiprofiler10ping --no-check-certificate

SESSION (Cookie) authenticationIn order to use the SESSION (Cookie) authentication a session ID must be generated The session ID can then be usedto access protected resources To generate a session ID the client must send a POST request with username passwordand optionally purpose The API supports three different methods of input x-www-form-urlencoded JSON and XML

Client request using x-www-form-urlencoded input

POST apicommon10loginHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson

username=usernameamppassword=passwordamppurpose=script XYZ

Server response

HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7

session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7

Client request using JSON input

POST apicommon10loginHost 127001Content-Type applicationjsonAccept applicationjson

username username password password purpose script XYZ

Server response



Client request using XML input

POST apicommon10loginHost 127001Content-Type textxmlAccept textxml

Server response


ltlogin username=user password=pass purpose=UI login gt

The client must include the Cookie header when accessing authenticated resources The session (cookie) expirationrules are the same as the ones used in the GUI of the product The rules can be changed from the Log-in Settings page

Client request to protected resource using the session ID

POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7

Server response

HTTP11 204 OK

Client request to protected resource using expiredinvalid session ID


Server response

HTTP11 401 AUTH_INVALID_SESSIONContent-Type applicationjson

error_id AUTH_INVALID_SESSION error_text Session ID is invalid

To end a previously started session the client sends a GET request to logout including a Cookie header with thesession ID

Client request to end a previously started session

GET apicommon10logoutHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7

Server response

HTTP11 204

Sample PHP script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication

ltphp

define(HOST 127001) IP address of Profiler

HTTP POSTfunction do_POST($url $string amp$info) $curl = curl_init() curl_setopt($curl CURLOPT_URL $url) curl_setopt($curl CURLOPT_SSLVERSION3) curl_setopt($curl CURLOPT_SSL_VERIFYPEER FALSE) curl_setopt($curl CURLOPT_SSL_VERIFYHOST 2) curl_setopt($curl CURLOPT_HEADER true) curl_setopt($curl CURLOPT_RETURNTRANSFER true) curl_setopt($curl CURLOPT_HTTPHEADER array(Content-Type applicationjson Accept applicationjson)) curl_setopt($curl CURLOPT_POST 1) curl_setopt($curl CURLOPT_POSTFIELDS $string) $output = curl_exec($curl) $info = curl_getinfo($curl) curl_close($curl)


HTTP GETfunction do_GET($url $session_key $session_id amp$info) $curl = curl_init() curl_setopt($curl CURLOPT_URL $url) curl_setopt($curl CURLOPT_SSLVERSION3) curl_setopt($curl CURLOPT_SSL_VERIFYPEER FALSE) curl_setopt($curl CURLOPT_SSL_VERIFYHOST 2) curl_setopt($curl CURLOPT_HEADER true) curl_setopt($curl CURLOPT_RETURNTRANSFER true) curl_setopt($curl CURLOPT_HTTPHEADER array(Accept applicationjson Cookie $session_key=$session_id)) curl_setopt($curl CURLOPT_HTTPGET true) $output = curl_exec($curl) $info = curl_getinfo($curl) curl_close($curl)


Post to create session id

$login_data = array(username =gt admin password =gt admin purpose =gt demonstrate SESSION authentication)$url = https HOST apicommon10login$output = do_POST($url json_encode($login_data) $info)

$output = do_POST($url json_encode($login_data) $info)

if ($info[http_code] = 200) echo Login Failedn echo $output exit(1)

$data = json_decode($output 1)$session_key = $data[session_key]$session_id = $data[session_id]

echo Login successful $session_key=$session_idn

Ping to test session authentication$url = https HOST apiprofiler10pingecho GET $urln

$info = array()$output = do_GET($url $session_key $session_id $info)


gt

Sample Python script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication


HOST = 127001

Lib functions

def do_POST(url string) HTTP POST


headers = Content-Length str(len(string)) Content-Type applicationjson Accept applicationjson

connrequest(POST url body=string headers=headers)




def do_GET(url session_key session_id) HTTP GET


headers = Content-Length 0 Content-Type applicationjson Accept applicationjson Cookie s=s (session_key session_id)






login_data = username admin password admin purpose demonstrate SESSION authentication

url = httpssapicommon10login HOST

output info = do_POST(url jsondumps(login_data))if (info[status] is not 200) print Login Failed print output sysexit(1)

data = jsonloads(output)session_key = data[session_key]session_id = data[session_id]

print Login successful s=s (session_key session_id)

url = httpssapiprofiler10ping HOST

Ping to test session authenticationoutput info = do_GET(url session_key session_id)

if (info[status] is 204) print Ping is successfulelse print Ping failed print output

Sample Perl script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication





sub GET($$$) my $req = HTTPRequest-gtnew(GET =gt $API_BASE shift) $req-gtheader(Accept =gt applicationjson)

my $session_key = shift my $session_id = shift $req-gtheader(Cookie =gt $session_key=$session_id)



sub POST($$) my $req = HTTPRequest-gtnew(POST =gt $API_BASE shift) $req-gtcontent_type(applicationjson) $req-gtcontent(encode_json(shift))

$req-gtheader(Accept =gt applicationjson)




my $login_data = username =gt admin password =gt admin purpose =gt demonstrate SESSION authentication

my $response = POST(apicommon10login $login_data)

die Login Failedn$response-gtdatan unless $response-gtcode == 200

my $data = decode_json($response-gtdata)my $session_key = $data-gtsession_keymy $session_id = $data-gtsession_idprint Login successful $session_key=$session_idn

Ping to test session authentication$response = GET(apiprofiler10ping $session_key $session_id)


Sample NetC script for SESSION (Cookie) authentication

Use the Ping resource to demonstrate SESSION (Cookie) authentication

using Systemusing SystemCollectionsGenericusing SystemNetusing SystemRuntimeSerializationJsonusing SystemTextusing SystemIOusing SystemNetSecurityusing SystemSecurityCryptographyX509Certificatesusing SystemWebScriptSerialization

namespace CascadeRestClient public class AuthResult public string session_key get set public string session_id get set

class Program callback used to validate the self-gen certificate in an SSL conversation private static bool ValidateRemoteCertificate(object sender X509Certificate cert X509Chain chain SslPolicyErrors policyErrors) return true


Starting to run rest string rootUrl = https + args[0] string requestUrl = rootUrl + apicommon10loginjson

var jsondata = new username = admin password = admin purpose = demonstrate SESSION authentication

Serialize anomymous type to json JavaScriptSerializer serializer = new JavaScriptSerializer() string postData = serializerSerialize(jsondata)

Login AuthResult r using (var response = MakeRequest(requestUrl WebRequestMethodsHttpPost null postData)) if (responseStatusCode = HttpStatusCodeOK) ConsoleWriteLine(Login Failed) LogResponse(response) return

r = ReadResponseltAuthResultgt(response) ConsoleWriteLine(stringFormat(Login successful 0=1 rsession_key rsession_id))

Ping to test session authentication requestUrl = rootUrl + apiprofiler10ping ConsoleWriteLine(GET + requestUrl)

using (var response = MakeRequest(requestUrl WebRequestMethodsHttpGet stringFormat(Cookie 0=1 rsession_key rsession_id))) if (responseStatusCode == HttpStatusCodeNoContent) ConsoleWriteLine(Ping is successful) else ConsoleWriteLine(Ping failed) LogResponse(response)


private static void LogResponse(HttpWebResponse response) using (Stream stream = responseGetResponseStream()) using (StreamReader reader = new StreamReader(stream EncodingUTF8)) String responseString = readerReadToEnd() ConsoleWriteLine(responseString)

private static T ReadResponseltTgt(HttpWebResponse response) where T class DataContractJsonSerializer jsonSerializer = new DataContractJsonSerializer(typeof(T)) object objResponse = jsonSerializerReadObject(responseGetResponseStream()) return objResponse as T

ltsummarygt Make request ltsummarygt lttypeparam name=Tgtreturn typelttypeparamgt ltparam name=requestUrlgturl for requestltparamgt ltparam name=actiongtHttp Verb Get Post etcltparamgt ltparam name=headergtadditional header except accept and content type ltparamgt ltparam name=requestDatagtData postedltparamgt ltreturnsgtltreturnsgt private static HttpWebResponse MakeRequest(string requestUrl string action string header string requestData = null) HttpWebRequest request = WebRequestCreate(requestUrl) as HttpWebRequest if (stringIsNullOrWhiteSpace(header)) requestHeadersAdd(header) requestContentType = applicationjson requestAccept = applicationjson requestMethod = action if (requestData == null) requestContentLength = 0 else ASCIIEncoding encoding = new ASCIIEncoding() byte[] byte1 = encodingGetBytes(requestData) requestContentLength = byte1Length using (Stream newStream = requestGetRequestStream()) newStreamWrite(byte1 0 byte1Length)

return requestGetResponse() as HttpWebResponse

OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code

Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script

All access to protected resources requires a valid access token To get an access token the client must send a POSTrequest with the access code The server will issue an access token that is valid for the next 1 hour and return it in thebody of the POST If the client script runs for more than 1 hour then it will need to generate another access tokenwhen the one that it has expires An expired token results into an error with HTTP code 401 and error_idAUTH_EXPIRED_TOKEN

Client request to generate an OAuth 20 access token

POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson

grant_type=access_codeampassertion=access code here

Server response

HTTP11 200 OKContent-Type applicationjson

access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600

Client request to protected resource using the OAuth 20 access token

POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod

Server response

HTTP11 204 OK

Client request to protected resource using expired OAuth 20 access token


Server response

HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson

error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired

Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code



ltphp

define(OAUTH_CODE ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)


HTTP POSTfunction do_POST($url $string amp$info) $curl = curl_init() curl_setopt($curl CURLOPT_URL $url) curl_setopt($curl CURLOPT_SSLVERSION3) curl_setopt($curl CURLOPT_SSL_VERIFYPEER FALSE) curl_setopt($curl CURLOPT_SSL_VERIFYHOST 2) curl_setopt($curl CURLOPT_HEADER true) curl_setopt($curl CURLOPT_RETURNTRANSFER true) curl_setopt($curl CURLOPT_HTTPHEADER array(Content-Type applicationx-www-form-urlencoded Accept applicationjson)) curl_setopt($curl CURLOPT_POST 1) curl_setopt($curl CURLOPT_POSTFIELDS $string)

curl_setopt($curl CURLOPT_POSTFIELDS $string) $output = curl_exec($curl) $info = curl_getinfo($curl) curl_close($curl)


HTTP GETfunction do_GET($url $access_token amp$info) $curl = curl_init() curl_setopt($curl CURLOPT_URL $url) curl_setopt($curl CURLOPT_SSLVERSION3) curl_setopt($curl CURLOPT_SSL_VERIFYPEER FALSE) curl_setopt($curl CURLOPT_SSL_VERIFYHOST 2) curl_setopt($curl CURLOPT_HEADER true) curl_setopt($curl CURLOPT_RETURNTRANSFER true) curl_setopt($curl CURLOPT_HTTPHEADER array(Accept applicationjson Authorization Bearer $access_token)) curl_setopt($curl CURLOPT_HTTPGET true) $output = curl_exec($curl) $info = curl_getinfo($curl) curl_close($curl)


Post to get access token based on the access code

$url = https HOST apicommon10oauthtoken$output = do_POST($url grant_type=access_codeampassertion= OAUTH_CODE $info)

if ($info[http_code] = 200) echo Post to get access token failedn echo $output exit(1)

$data = json_decode($output 1)$access_token = $data[access_token]$expires_in = $data[expires_in]echo Post to get token id is successfulnToken $access_tokennecho The token will expire in $expires_in secondsn

Ping to test OAuth 20 authentication$url = https HOST apiprofiler10pingecho GET $urln

$info = array()$output = do_GET($url $access_token $info)

if ($info[http_code] == 204) echo OAuth 20 authentication is successfuln else echo OAuth 20 authentication failedn echo $output

gt

Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code




OAUTH_CODE = ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9

HOST = 127001

Lib functions



headers = Content-Length str(len(string)) Content-Type applicationx-www-form-urlencoded Accept applicationjson





def do_GET(url access_token) HTTP GET


headers = Content-Length 0 Content-Type applicationjson Accept applicationjson Authorization Bearer s access_token






url = httpssapicommon10oauthtoken HOST

output info = do_POST(url grant_type=access_codeampassertion=s OAUTH_CODE)if (info[status] is not 200) print Post to get access token failed print output sysexit(1)

data = jsonloads(output)access_token = data[access_token]expires_in = data[expires_in]

print Post to get token id is successfulprint Token s access_tokenprint The token will expire in s seconds expires_in

Ping to test OAuth 20 authenticationurl = httpssapiprofiler10ping HOSToutput info = do_GET(url access_token)

if (info[status] is 204) print OAuth 20 authentication is successfulelse print OAuth 20 authentication failed print output

Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code






our $OAUTH_CODE = ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9


sub GET($$) my $req = HTTPRequest-gtnew(GET =gt $API_BASE shift) $req-gtheader(Accept =gt applicationjson)

my $access_token = shift $req-gtheader(Authorization =gt Bearer $access_token)



sub POST($$) my $req = HTTPRequest-gtnew(POST =gt $API_BASE shift) $req-gtcontent_type(applicationjson) $req-gtcontent(shift)

$req-gtheader(Accept =gt applicationjson) $req-gtheader(Content-Type =gt applicationx-www-form-urlencoded)




my $url = apicommon10oauthtokenmy $response = POST($url grant_type=access_codeampassertion=$OAUTH_CODE)

die Post to get access token failedn$response-gtdatan unless $response-gtcode == 200

my $data = decode_json($response-gtdata)my $access_token = $data-gtaccess_tokenmy $expires_in = $data-gtexpires_inprint Post to get token id is successfulnToken $access_tokennprint The token will expire in $expires_in secondsn

Ping to test OAuth 20 authentication$response = GET(apiprofiler10ping $access_token)

if ($response-gtcode == 204) print OAuth 20 authentication is successfuln else print OAuth 20 authentication failedn print $response-gtdata

Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code



using Systemusing SystemCollectionsGenericusing SystemNetusing SystemRuntimeSerializationJsonusing SystemTextusing SystemIOusing SystemNetSecurityusing SystemSecurityCryptographyX509Certificates

namespace CascadeRestClient public class OAuthResult public string access_token get set public string expires_in get set



Starting to run rest string rootUrl = https + args[0] string OAUTH_CODE = ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==

string requestUrl = rootUrl + apicommon10oauthtoken

string postData = grant_type=access_codeampassertion= + OAUTH_CODE OAuthResult r

Login using (var response = MakeRequest(requestUrl WebRequestMethodsHttpPostapplicationx-www-form-urlencoded null postData)) if (responseStatusCode = HttpStatusCodeOK) ConsoleWriteLine(Login Failed) LogResponse(response) ConsoleRead() return

r = ReadResponseltOAuthResultgt(response) ConsoleWriteLine(Post to get token id is successfulnToken + raccess_token) ConsoleWriteLine(stringFormat(The token will expire in 0 secondsrexpires_in))


using (var response = MakeRequest(requestUrl WebRequestMethodsHttpGetapplicationjson stringFormat(Authorization Bearer 0 raccess_token))) if (responseStatusCode == HttpStatusCodeNoContent) ConsoleWriteLine(OAuth 20 authentication is successful)

ConsoleWriteLine(OAuth 20 authentication is successful) else ConsoleWriteLine(OAuth 20 authentication failed) LogResponse(response) catch (Exception e) ConsoleWriteLine(eMessage) ConsoleRead()


private static T ReadResponseltTgt(HttpWebResponse response) where T class

DataContractJsonSerializer jsonSerializer = new DataContractJsonSerializer(typeof(T)) object objResponse = jsonSerializerReadObject(responseGetResponseStream()) return objResponse as T

ltsummarygt Make request ltsummarygt ltparam name=requestUrlgturl for requestltparamgt ltparam name=actiongtHttp Verb Get Post etcltparamgt ltparam name=requestDatagtData postedltparamgt ltreturnsgtltreturnsgt private static HttpWebResponse MakeRequest(string requestUrl string action string contenttype string header string requestData = null) HttpWebRequest request = WebRequestCreate(requestUrl) as HttpWebRequest try if (stringIsNullOrWhiteSpace(header)) requestHeadersAdd(header) requestContentType = contenttype requestAccept = applicationjson requestMethod = action if (requestData == null) requestContentLength = 0 else ASCIIEncoding encoding = new ASCIIEncoding() byte[] byte1 = encodingGetBytes(requestData) requestContentLength = byte1Length using (Stream newStream = requestGetRequestStream()) newStreamWrite(byte1 0 byte1Length)

var response = requestGetResponse() as HttpWebResponse return response catch (Exception) requestAbort() throw

Resources

[ id string versions [ string ] ]

Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]

Services List servicesGet information for supported API namespaces

GET httpsdeviceapicommon10services

AuthorizationThis request requires authorization

Response BodyOn success the server returns a response body with the following structure

Property Name Type Description Notes

services ltarray ofltobjectgtgt List of namespaces and versions supported by the system

services[service] ltobjectgt Object representing an API serviceservices[service]id ltstringgt ID of the service such as profiler

services[service]versions ltarray ofltstringgtgt List of versions for a given service

services[service]versions[version] ltstringgt Version of the service Optional

Auth_info Get authentication infoGet information for supported authentication methods

GET httpsdeviceapicommon10auth_info



JSON

JSON

login_banner string specify_purpose boolean supported_methods [ string ]

Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in

password string purpose string username string

Example username username password password purpose Purpose for loging in


auth_info ltobjectgt Common authentication information

auth_infologin_banner ltstringgt Login banner that a client should display before userslogin

auth_infospecify_purpose ltbooleangt Flag describing if the login purpose should be specified

auth_infosupported_methods ltarray ofltstringgtgt List of supported authentication methods

auth_infosupported_methods[method] ltstringgt One method from the list of supported authenticationmethods Optional Values BASIC COOKIE OAUTH_2_0

Login LoginStart cookie based authentication session

POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string


ParametersProperty Name Type Description Notes

username ltstringgt User name that identifies the user to the system Optionalpassword ltstringgt User account password Optional

purpose ltstringgt Login purpose describing why the user logs in to thesystem Optional

Request BodyProvide a request body with the following structure


login ltobjectgt Specification for request to log inloginpassword ltstringgt Password

loginpurpose ltstringgt Login purpose describing why the user logs in to thesystem Optional

loginusername ltstringgt User name that identifies the user to the system


JSON

session_id string session_key string

Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63

access_token string allowed_signature_types [ string ] expires_in number state string token_type string

Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=

token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas


login ltobjectgt Response for login requestloginsession_id ltstringgt Value of the session cookie

loginsession_key ltstringgt Name of the session cookie that should be stored by theclient and presented on subsequent requests

Oauth Get OAuth tokenGet a OAuth token based on OAuth code

POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string



grant_type ltstringgt The type of authorization method used to grant this tokenThe value must be access_code

assertion ltstringgt The access code generated by the system on the OAuthAccess page

state ltstringgt Optional client-provided value that will be echoed back in theresponse Optional

Request BodyDo not provide a request body



token_response ltobjectgt TokenResponse object

token_responseaccess_token ltstringgt The generated access token that can be used to accessprotected resources

token_responseallowed_signature_types ltarray ofltstringgtgt Array of allowed signature methods

JSON

JSON

token_responseallowed_signature_types[value] ltstringgt Allowed signature method Optional

token_responseexpires_in ltnumbergt How long this token is valid for

token_responsestate ltstringgt Included if the state parameter was passed in the tokenrequest Optional

token_responsetoken_type ltstringgt The token type Only bearer is currently supported

Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user

GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string



client_id ltstringgt Client identifier Optional

response_type ltstringgt The value must be code for requesting an access code andtoken for an access token

desc ltstringgt Description of the use of this code Used in audit trail logs Optional

state ltstringgt Included if the state parameter was passed in the tokenrequest Optional

redirect_uri ltstringgt URI that will be used for redirect Optional

Response BodyOn success the server does not provide any body in the responses

Ping PingSimple test of service availability

GET httpsdeviceapicommon10ping



Logout LogoutEnd cookie based authentication session

POST httpsdeviceapicommon10logoutbanner_disagree=string



banner_disagree ltstringgt Used when the session is being ended due to the user notagreeing to the login banner conditions Optional



Info Get infoGet appliance info

device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string

Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260

GET httpsdeviceapicommon10info




info ltobjectgt Information about the systeminfodevice_name ltstringgt Name of the device that the API is running on Optionalinfohw_version ltstringgt Unsupported Optional

infomgmt_addresses ltarray ofltstringgtgt List of IP addresses

infomgmt_addresses[ip] ltstringgt IP address Optional

infomodel ltstringgt Model of the device Optionalinfoserial ltstringgt Serial number of the device Optionalinfosw_version ltstringgt Version of the software that is running on the device Optional

Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status codeand additional information in the response body

error_id error identifier error_text error description error_info error specific data structure optional

The table below lists the possible errors and the associated HTTP status codes that may returned

Error ID HTTP Status Comments

INTERNAL_ERROR 500 Internal server errorAUTH_REQUIRED 401 The requested resource requires authenticationAUTH_INVALID_CREDENTIALS 401 Invalid username andor passwordAUTH_INVALID_SESSION 401 Session ID is invalid

AUTH_EXPIRED_PASSWORD 403 The password must be changed Access only to password changeresources

AUTH_DISABLED_ACCOUNT 403 Account is either temporarily or permanently disabledAUTH_FORBIDDEN 403 User is not authorized to access the requested resourceAUTH_INVALID_TOKEN 401 OAuth access token is invalidAUTH_EXPIRED_TOKEN 401 OAuth access token is expiredAUTH_INVALID_CODE 401 OAuth access code is invalidAUTH_EXPIRED_CODE 401 OAuth access code is expiredRESOURCE_NOT_FOUND 404 Requested resource was not foundHTTP_INVALID_METHOD 405 Requested method is not available for this resource

JSON

HTTP_INVALID_HEADER 400 An HTTP header was malformedREQUEST_INVALID_INPUT 400 Malformed input structureURI_INVALID_PARAMETER 400 URI parameter is not supported or malformedURI_MISSING_PARAMETER 400 Missing required parameter

Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues

BASIC Authentication

Sample PHP script for BASIC authentication

Sample Python script for BASIC authentication

Sample Perl script for BASIC authentication

Sample NetC script for BASIC authentication

Sample CURL command (BASIC authentication)

Sample WGET command (BASIC authentication)

SESSION (Cookie) authentication

Sample PHP script for SESSION (Cookie) authentication

Sample Python script for SESSION (Cookie) authentication

Sample Perl script for SESSION (Cookie) authentication


OAuth 20 authentication

Sample PHP script for OAuth 20 authentication

Sample Python script for OAuth 20 authentication

Sample Perl script for OAuth 20 authentication

Sample NetC script for OAuth 20 authentication

Resources

Services List services

Auth_info Get authentication info

Login Login

Oauth Get OAuth token

Oauth Get Oauth codeimplicit token

Ping Ping

Logout Logout

Info Get info

Error Codes

Overview

OverviewThe documentation pages in this section describe the RESTful APIs included with Cascade Profiler and Cascade Expressproducts It is assumed that the reader has practical knowledge of RESTful APIs so the documentation does not go intodetail about what REST is and how to use it Instead the documentation focuses on what data can be accessed andhow to access it

The primary focus of the current version of the API is on providing access to common data The following informationcan be accessed via the API

System information (serial number model etc)Information and resources for authenticating (login logout oauth 20 etc)

Details about REST resources can be found in the Resources section

SSLAll communication to the profiler is SSL encrypted on Port 443 There is no support for access to the profiler on thestandard HTTP port 80

CiphersThe ciphers supported by the Profiler may change depending on security setting (eg FIPS mode) Any client wheninitiating a request must include one or more ciphers available in the Profilers configured list Otherwise the client willreceive an SSL error indicating that there is no cipher overlap and will be unable to connect

CertificateThe profiler by default uses a self-signed certificate for SSL communication The client should be able to handle this bypermitting self-signed certificates

ExamplesUsing the curl command line client to request the services resource on a non-FIPS box The -k switch is used to allowthe self-signed certificate and a cipher suite (SSL v3) is provided

curl -k -3 httpshostname443apicommon10services

Using the curl command line client to request the services resource on a FIPS box An explicit cipher is selected

curl --ciphers rsa_aes_256_sha -k httpshostname443apicommon10services

Known IssuesSome clients such as Curl (both as a library and a command line executable) do not support both an explicit cipherlist and a cipher suite The following command will fail on a FIPS Profiler

curl --ciphers rsa_aes_256_sha -3 -k httpshostname443apicommon10services

This is because the cipher suite (-3) overrides the --ciphers argument Clients with this issue will receive a no cipheroverlap error even if they have explicitly provided a cipher that is known to be FIPS compliant

BASIC AuthenticationFor BASIC authentication the request header Authorization must be set to a base64-encoded string ofusernamepassword

If the Authorization header is not provided the WWW-Authenticate response header is returned Basicauthentication has a built-in support in various tools Refer to the coding examples

Example of client request to protected resource using Basic Authentication

POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Basic YWRtaW46YWRtaW4=

Server response

HTTP11 204 OK


ltphp







gt




Lib functions






























return false















Server response






Server response





Server response






Server response

HTTP11 204 OK



Server response






Server response

HTTP11 204


ltphp















gt



HOST = 127001

Lib functions




































































Server response





Server response

HTTP11 204 OK



Server response






ltphp















gt






HOST = 127001

Lib functions
































































Resources
















JSON

JSON























JSON






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes


ltphp







gt




Lib functions






























return false















Server response






Server response





Server response






Server response

HTTP11 204 OK



Server response






Server response

HTTP11 204


ltphp















gt



HOST = 127001

Lib functions




































































Server response





Server response

HTTP11 204 OK



Server response






ltphp















gt






HOST = 127001

Lib functions
































































Resources
















JSON

JSON























JSON






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes



Lib functions






























return false















Server response






Server response





Server response






Server response

HTTP11 204 OK



Server response






Server response

HTTP11 204


ltphp















gt



HOST = 127001

Lib functions




































































Server response





Server response

HTTP11 204 OK



Server response






ltphp















gt






HOST = 127001

Lib functions
































































Resources
















JSON

JSON























JSON






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes


















return false















Server response






Server response





Server response






Server response

HTTP11 204 OK



Server response






Server response

HTTP11 204


ltphp















gt



HOST = 127001

Lib functions




































































Server response





Server response

HTTP11 204 OK



Server response






ltphp















gt






HOST = 127001

Lib functions
































































Resources
















JSON

JSON























JSON






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes















Server response






Server response





Server response






Server response

HTTP11 204 OK



Server response






Server response

HTTP11 204


ltphp















gt



HOST = 127001

Lib functions




































































Server response





Server response

HTTP11 204 OK



Server response






ltphp















gt






HOST = 127001

Lib functions
































































Resources
















JSON

JSON























JSON






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes






Server response

HTTP11 204


ltphp















gt



HOST = 127001

Lib functions




































































Server response





Server response

HTTP11 204 OK



Server response






ltphp















gt






HOST = 127001

Lib functions
































































Resources
















JSON

JSON























JSON






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes








gt



HOST = 127001

Lib functions




































































Server response





Server response

HTTP11 204 OK



Server response






ltphp















gt






HOST = 127001

Lib functions
































































Resources
















JSON

JSON























JSON






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes


HOST = 127001

Lib functions




































































Server response





Server response

HTTP11 204 OK



Server response






ltphp















gt






HOST = 127001

Lib functions
































































Resources
















JSON

JSON























JSON






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes













































Server response





Server response

HTTP11 204 OK



Server response






ltphp















gt






HOST = 127001

Lib functions
































































Resources
















JSON

JSON























JSON






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes












gt






HOST = 127001

Lib functions
































































Resources
















JSON

JSON























JSON






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes



HOST = 127001

Lib functions
































































Resources
















JSON

JSON























JSON






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes











































Resources
















JSON

JSON























JSON






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes
















JSON

JSON























JSON






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes























JSON






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes






















JSON

JSON












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes












































JSON


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes


Contents

Overview

Overview

SSL

Ciphers

Certificate

Examples

Known Issues


















Resources



Login Login



Ping Ping

Logout Logout

Info Get info

Error Codes

riverbed cascade profiler common rest api v1€¦ · overview overview the documentation pages in...

Documents