REST API doc fixes and Python example

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"}'

docs/source/advanced/restapi/restapi_usage/restapi_usage.rst

@@ -37,14 +37,14 @@ where:
 
 Example: ::
 
-    curl -X GET --cacert /root/ca-cert.pem 'https://<FQDN of xCAT MN>/xcatws/nodes?userName=root&userPW=cluster'
+    curl -X GET -k 'https://<FQDN of xCAT MN>/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://<FQDN of xCAT MN>/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://<FQDN of xCAT MN>/xcatws/<resource>?<parameters>
+    curl -X GET -k -H X-Auth-Token:5cabd675-bc2e-4318-b1d6-831fd1f32f97 'https://<FQDN of xCAT MN>/xcatws/<resource>?<parameters>
 
 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 <https://github.com/xcat2/xcat-core/blob/master/xCAT-server/xCAT-wsapi/xcatws-test.py>`_: ::
+
+    ./xcatws-test.py --user wsuser -password cluster_rest --xcatmn <FQDN of xCAT MN>
+
 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 <https://github.com/xcat2/xcat-core/blob/master/xCAT-server/xCAT-wsapi/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 <FQDN of xCAT MN> -t
     ./xcatws-test.sh -u root -p cluster -h <FQDN of xCAT MN> -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'
 

xCAT-server/xCAT-wsapi/xcatws-test.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python
+"""Usage:
+  xcatws_test.py [--xcatmn=<xcatmn>] [--user=<user>] [--password=<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)

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,
             },