Updates example.py to be more explicit and readable

Updated example.py to be more explicit about initial credentials.
Updated comments to be more readable.
Updated commented call to requiredFields to show use of action
parameter with the 'create' action.
Updated order creation example to use descriptive variables instead of
reusing same 'order' variable.

Author: tnydwrds

example.py

@@ -1,75 +1,80 @@
 import datetime
 import ox3apiclient
-import urllib
 
-usr = ''
-pwd = ''
+# User credentials
+email_address = '' 
+password = ''
 
+# OAuth credentials. These will be supplied by your Account Manager or Support.
 domain = ''
 realm = ''
 consumer_key = ''
 consumer_secret = ''
 
+
 ox = ox3apiclient.OX3APIClient(domain, realm, consumer_key, consumer_secret)
 
 # Step 1. Fetch temporary request token.
 ox.fetch_request_token()
 
 # Step 2. Log in to SSO server and authorize token.
-ox.authorize_token(usr, pwd)
+ox.authorize_token(email_address, password)
 
 # Step 3. Swap temporary request token for permanent access token.
-ox.fetch_access_token()
-
-# Step 4. Validate your access token.
-# You'll more than likely want to call the validate_session method, but you may
-# need to grab the access token directly for some reason (maybe this is a
-# server-side proxy between a custom site and the API?). Regardless, you can get
-# the access token when you call fetch_access_token:
-#
+# If you need to store the access token yourself you can do so with something
+# similar to:
 #   token_str = ox.fetch_access_token()
 #   access_token = urlparse.parse_qs(token_str)['oauth_token'][0]
-# 
-ox.validate_session()
+ox.fetch_access_token()
 
-# Or manually validate your access token (but you will be resonpsible for
-# passing the requisite openx3_access_token for all successive API requests).
+# Step 4. Validate your access token.
+# You'll more than likely want to call the validate_session method, but you can
+# manually validate your access token if needed. You will be resonpsible for
+# passing the requisite openx3_access_token for all successive API requests. A
+# method might look like the following:
 #   token_str = ox.fetch_access_token()
 #   access_token = urlparse.parse_qs(token_str)['oauth_token'][0]
 #   cookie_header = {'Cookie': 'openx3_access_token=' + access_token}
 #   ox.request(url='http://youruidomain.com/ox/3.0/a/session/validate',
 #       method='PUT',
 #       headers=cookie_header)
+ox.validate_session()
 
 
+# Now that we have connected let's try making a few API requests.
 # Print out account names. We use overload=medium to get more than just a
 # listing of ids.
 accounts = ox.get('/a/account?overload=medium')
 for account in accounts:
-    msg = '\tAccount ID: %s, Account Name: %s'
+    msg = 'Account ID: %s, Account Name: %s'
     print(msg % (account['id'], account['name']))
 
 # We won't test object creation with accounts because they can't be deleted
-# currently.
+# currently. Instead, we will create an order under an advertiser account.
 account_id = 0 #<= Replace with a valid advertiser account id for your instance.
+
 if account_id:
-    # required_fields = ox.get('/a/order/requiredFields')
+
+    # You can check to see what fields are required for the create action.
+    # required_fields = ox.get('/a/order/requiredFields?action=create')
     # print(required_fields) #=> {u'status': u'string', u'name': u'string', u'account_id': u'int', u'start_date': u'datetime'}
+    
+    # OX3APIClient methods accept Python dicts for data parameters, so we can
+    # define an order as a normal dict.
     order = {
         'status': 'Active',
         'name': 'OX3APIClient Object Creation Test',
         'account_id': account_id,
         'start_date': datetime.datetime.today().strftime('%Y-%m-%d %H:%M:%S'),
     }
 
-    # OX3APIClient methods accept dicts for data parameters.
-    order = ox.post('/a/order', data=order)
+    new_order = ox.post('/a/order', data=order)
     # print(order) #=> {u'id': 12345}
-    print('Created order id %s' % order['id'])
+    print('Created order id %s' % new_order['id'])
 
-    # Lets get all the details on the order we just created.
-    order = ox.get('/a/order/%s' % order['id'])
-    print(order)
+    # Let's get all the details on the order we just created.
+    existing_order = ox.get('/a/order/%s' % new_order['id'])
+    print(existing_order)
 
 # Log out.
 ox.delete('/a/session')