diff --git a/docs/source/advanced/restapi/restapi_resource/restapi_reference.rst b/docs/source/advanced/restapi/restapi_resource/restapi_reference.rst index d8b74d00d..b641252be 100644 --- a/docs/source/advanced/restapi/restapi_resource/restapi_reference.rst +++ b/docs/source/advanced/restapi/restapi_resource/restapi_reference.rst @@ -15,7 +15,7 @@ POST - Create a token. **Example:** -Aquire a token for user 'root'. :: +Acquire a token for user 'root'. :: curl -X POST -k 'https://127.0.0.1/xcatws/tokens?userName=root&userPW=cluster&pretty=1' -H Content-Type:application/json --data '{"userName":"root","userPW":"cluster"}' diff --git a/docs/source/advanced/restapi/restapi_usage/restapi_usage.rst b/docs/source/advanced/restapi/restapi_usage/restapi_usage.rst index 301a0a770..09c65095c 100644 --- a/docs/source/advanced/restapi/restapi_usage/restapi_usage.rst +++ b/docs/source/advanced/restapi/restapi_usage/restapi_usage.rst @@ -37,14 +37,14 @@ where: Example: :: - curl -X GET --cacert /root/ca-cert.pem 'https:///xcatws/nodes?userName=root&userPW=cluster' + curl -X GET -k 'https:///xcatws/nodes?userName=root&userPW=cluster' Access Token ------------ xCAT also supports the use the Access Token to replace the using of username+password in every access. Before accessing any resource, you need get a token with your account (username+password) :: - # curl -X POST --cacert /root/ca-cert.pem \ + # curl -X POST -k \ 'https:///xcatws/tokens?pretty=1' -H Content-Type:application/json --data \ '{"userName":"root","userPW":"cluster"}' { @@ -56,7 +56,7 @@ xCAT also supports the use the Access Token to replace the using of username+pas Then in the subsequent REST API access, the token can be used to replace the user account (username+password) :: - curl -X GET --cacert /root/ca-cert.pem -H X-Auth-Token:5cabd675-bc2e-4318-b1d6-831fd1f32f97 'https:///xcatws/? + curl -X GET -k -H X-Auth-Token:5cabd675-bc2e-4318-b1d6-831fd1f32f97 'https:///xcatws/? The validity of token is 24 hours. If an old token has expired, you will get a 'Authentication failure' error. Then you need reacquire a token with your account. @@ -183,10 +183,17 @@ Testing the API Normally you will make REST API calls from your code. You can use any language that has REST API bindings (most modern languages do). +An Example of How to Use xCAT REST API from Python +-------------------------------------------------- + +Refer to the file `/opt/xcat/ws/xcatws-test.py `_: :: + + ./xcatws-test.py --user wsuser -password cluster_rest --xcatmn + An Example of How to Use xCAT REST API from PERL ------------------------------------------------ -Refer to the file /opt/xcat/ws/xcatws-test.pl: :: +Refer to the file `/opt/xcat/ws/xcatws-test.pl `_: :: ./xcatws-test.pl -m GET -u "https://127.0.0.1/xcatws/nodes?userName=root&userPW=cluster" @@ -202,9 +209,9 @@ It can be used as an example script to access and control xCAT resources. From t ./xcatws-test.sh -u root -p cluster -h -t ./xcatws-test.sh -u root -p cluster -h -c -t -But for exploration and experimentation, you can make API calls from your browser or using the **curl** command. +But for exploration and experimentation, you can make API calls from your browser or by using the **curl** command. -To make an API call from your browser, uses the desired URL from this document. To simplify the test step, all the examples for the resources uses 'curl -k' to use insecure http connection and use the 'username+password' to authenticate the user. :: +To make an API call from your browser, use the desired URL from this document. To simplify the test step, all the examples for the resources use 'curl -k' for unsecure http connection and use the 'username+password' to authenticate the user. :: curl -X GET -k 'https://myserver/xcatws/nodes?userName=xxx&userPW=xxx&pretty=1' diff --git a/xCAT-server/xCAT-wsapi/xcatws-test.py b/xCAT-server/xCAT-wsapi/xcatws-test.py new file mode 100755 index 000000000..7fa06322a --- /dev/null +++ b/xCAT-server/xCAT-wsapi/xcatws-test.py @@ -0,0 +1,96 @@ +#!/usr/bin/env python +"""Usage: + xcatws_test.py [--xcatmn=] [--user=] [--password=] +""" +import requests +import json +import sys + +XCATMN = "127.0.0.1" +username = "wsuser" +password = "cluster_rest" +# +# Gather user inputs if any, otherwise defaults above are used +# +try: + from docopt import docopt, DocoptExit + arguments = docopt(__doc__) + if arguments['--xcatmn']: + XCATMN = arguments['--xcatmn'] + if arguments['--user']: + username = arguments['--user'] + if arguments['--password']: + password = arguments['--password'] +except ImportError: + print "WARNING: docopt is not installed, will continue with hard coded defaults..." +except DocoptExit as e: + # Invalid arguments + print e + sys.exit(1) + +REST_ENDPOINT = "https://" + XCATMN + "/xcatws" +create_node = REST_ENDPOINT + "/nodes/" +get_all_nodes = REST_ENDPOINT + "/nodes/" +get_token = REST_ENDPOINT + "/tokens" + +# +# Create a test node object +# +testnode_name = "rest_api_node" +testnode_group = "all" +testnode_mgt = "ipmi" +testnode_data = {'groups': testnode_group,'mgt': testnode_mgt} +try: + new_node = requests.post(create_node + testnode_name + "?userName=" + username + "&userPW=" + password, verify=False, headers={'Content-Type': 'application/json'}, data=json.dumps(testnode_data)) + + if new_node.content: + # Display node creation error + print "Failed to create new node " + testnode_name + print new_node.content + sys.exit(1) + else: + print "New node definition created for " + testnode_name + ".\n" +except requests.exceptions.HTTPError as e: + print ("Http Error:",e) + sys.exit(1) +except requests.exceptions.ConnectionError as e: + print "Error connecting to xCAT management node " + XCATMN + print e + sys.exit(1) +except requests.exceptions.Timeout as e: + print "Timeout connecting to xCAT management node " + XCATMN + print e + sys.exit(1) +except requests.exceptions.RequestException as e: + print "Unexpected error connecting to xCAT management node " + XCATMN + print e + sys.exit(1) +except AttributeError as e: + print "AttributeError caught, you may need to update the Perl libraries." + print e + sys.exit(1) +except Exception as e: + print "Unexpected error." + print e + sys.exit(1) + +# +# Send a request to get all nodes, passing in user and password +# +all_nodes = requests.get(get_all_nodes + "?userName=" + username + "&userPW=" + password, verify=False) + +# Display returned data +print "List of all nodes extracted with userid and password:" +print all_nodes.content +# +# Send a request to get all nodes, passing in a token +# +user_data = {'userName': username,'userPW': password} +token = requests.post(get_token, verify=False, headers={'Content-Type': 'application/json'}, data=json.dumps(user_data)) +all_nodes = requests.get(get_all_nodes, verify=False, headers={'X-Auth-Token': token.json()['token']['id']}) + +# Display returned data +print "List of all nodes extracted with authentication token:" +print all_nodes.content + +sys.exit(0) diff --git a/xCAT-server/xCAT-wsapi/xcatws.cgi b/xCAT-server/xCAT-wsapi/xcatws.cgi index 099a905bd..84bd7c184 100755 --- a/xCAT-server/xCAT-wsapi/xcatws.cgi +++ b/xCAT-server/xCAT-wsapi/xcatws.cgi @@ -1251,7 +1251,7 @@ my %URIdef = ( POST => { desc => "Create a token.", usage => "||An array of all the global configuration list.|", - example => "|Aquire a token for user \'root\'.|POST|/tokens {\"userName\":\"root\",\"userPW\":\"cluster\"}|{\n \"token\":{\n \"id\":\"a6e89b59-2b23-429a-b3fe-d16807dd19eb\",\n \"expire\":\"2014-3-8 14:55:0\"\n }\n}|", + example => "|Acquire a token for user \'root\'.|POST|/tokens {\"userName\":\"root\",\"userPW\":\"cluster\"}|{\n \"token\":{\n \"id\":\"a6e89b59-2b23-429a-b3fe-d16807dd19eb\",\n \"expire\":\"2014-3-8 14:55:0\"\n }\n}|", fhandler => \&nonobjhdl, outhdler => \&tokenout, },