Merge pull request #87 from CiscoDevNet/kl-redirects

Updating lab IDs and implementing redirects

Author: klevenstein

labs/coding-101-rest-basics-ga/coding-101-rest-basics-ga.json

@@ -1,4 +1,5 @@
 {
+  "redirectTo": "what-are-rest-apis",
   "labId": "coding-101-rest-basics-ga",
   "title": "Coding 101 - REST API Basics",
   "slug": "Learn the basics of REST APIs. Use POSTMAN and the API for the DNA Center to learn how to make a REST API call.",
@@ -66,6 +67,5 @@
   ],
   "authors": [
   	{"name": "mcampos", "email": "marcocam@cisco.com"}
-  ],
-  "redirectTo": "what-are-rest-apis"
+  ]
 }

labs/coding-102-rest-python-ga/coding-102-rest-python-ga.json

@@ -1,4 +1,5 @@
 {
+  "redirectTo": "intro-python-part2",
   "labId": "coding-102-rest-python-ga",
   "title": "Coding 102: Calling REST APIs from Python",
   "slug": "Learn the basics of how to call and consume a REST API in Python",
@@ -63,6 +64,5 @@
   "authors": [
     {"name": "brtiller", "email": "brtiller@cisco.com"}
   ],
-  "active": true,
-  "redirectTo": "intro-python-part2"
+  "active": true
 }

labs/coding-201-parsing-xml/coding-201-parsing-xml.json

@@ -1,5 +1,6 @@
 {
-  "labId": "parsing-xml",
+  "redirectTo": "parsing-xml",
+  "labId": "coding-201-parsing-xml",
   "title": "Parsing XML",
   "slug": "Learn the basics of how to use parse XML results using Python.",
   "byod": true,
@@ -13,7 +14,7 @@
       "file": "3.md"},
     {"title": "Step 4: Get XML elements in Python",
       "file": "4.md"},
-    {"title": "Step 5: Find additional resources", 
+    {"title": "Step 5: Find additional resources",
       "file": "5.md"}
   ],
   "tags": [

labs/coding-202-parsing-json/coding-202-parsing-json.json

@@ -1,13 +1,14 @@
 {
-  "labId": "parsing-json",
+  "redirectTo": "parsing-json",
+  "labId": "coding-202-parsing-json",
   "title": "Parsing JSON",
   "slug": "Learn the basics of how to use parse JSON results using Python.",
   "byod": true,
   "time": "15",
   "files": [
     {"title": "Step 1: Make an HTTP REST call with Python",
       "file": "1.md"},
-    {"title": "Step 2: Use the JSON Python library", 
+    {"title": "Step 2: Use the JSON Python library",
       "file": "2.md"},
     {"title": "Step 3: Iterate through a JSON dictionary in Python",
       "file":"3.md"},

labs/parsing-json/1.md

@@ -0,0 +1,107 @@
+# Parsing JSON using Python
+
+In this Learning Lab, you learn the basics of parsing JSON content using Python. The example runs a query on the [ACI Always-On Sandbox](https://devnetsandbox.cisco.com/RM/Diagram/Index/5a229a7c-95d5-4cfd-a651-5ee9bc1b30e2?diagramType=Topology "ACI Always-On Sandbox") to request data for available configuration on the fabric. You will then parse this returned data and print it to the screen for human readability.  
+
+To learn more about ACI and its API, you can review the DevNet [Learning Lab track for ACI programmability](https://developer.cisco.com/learning/tracks/aci-programmability), which teaches a variety of different ways to interact with ACI programmatically.  ACI is used as a basis for these labs as the managed object model within ACI allows us to query the same object or class within the fabric and return both XML and JSON data structures, simply based on changing the file-type within the REST URL.
+
+## Objectives
+
+When you have completed this Learning Lab, you will be able to:
+
+* Understand the basics of reading and parsing HTTP content using Python.
+* Learn how to use Python to extract only the JSON data you want using the JSON library.
+
+## Prerequisites
+
+* Complete the [Coding Fundamentals](https://developer.cisco.com/learning/modules/programming-fundamentals) and [REST API Fundamentals](https://developer.cisco.com/learning/modules/rest-api-fundamentals) Learning Lab modules if you are unfamiliar with Python and retrieving results from a RESTful service and the [Parsing XML using Python Lab](lab/coding-201-parsing-xml/step/1 "Parsing XML using Python Lab") for a similar approach to retrieving data using XML.
+
+* You should also have a basic familiarity with JSON. Otherwise, consider visiting the [W3Schools JSON Tutorial](https://www.w3schools.com/js/js_json_intro.asp "W3Schools JSON Tutorial") to get a firm base to build upon.
+
+* For this lab, use Python 3.4+. To verify your version, enter the following command in a terminal:
+
+```
+    python --version
+```
+
+If you are on a DevNet Zone station, the correct version of Python should already be installed.
+
+# Step 1: Make an HTTP REST call with Python
+
+> **Note**: This lab leverages the DevNet Always-On ACI Sandbox, however you can substitute this with a local APIC if you have one available.  The sets of sample code contained within this lab will not perform any write or configuration actions against the fabric; they will only request currently configured data.
+
+To get started, this walk-through shows creating a simple Python script that sends an HTTP request to the ACI sandbox.
+
+1. Open a text editor and create a file named `get-tenant-json.py`.
+3. Add the following lines to `get-tenant-json.py`:
+
+  ```python
+  import requests
+  # We need to import the JSON library just to handle our request to the APIC for login
+  import json
+  # We need to log in to the APIC and gather a token, before we can access any data
+# Let's construct a request with a body
+
+# We'll need to disable certificate warnings
+requests.packages.urllib3.disable_warnings()
+
+# We need to have a body of data consisting of a username and password to gather a cookie from APIC
+encoded_body = json.dumps({
+	        "aaaUser": {
+		        "attributes": {
+			        "name": "admin",
+			        "pwd": "ciscopsdt"
+                 }
+            }
+})
+
+# Now lets make the request and store the data
+resp = requests.post("https://sandboxapicdc.cisco.com/api/aaaLogin.json", data=encoded_body, verify=False)
+
+# This stores the received APIC-cookie from the login as a value to be used in subsequent REST calls
+header = {"Cookie": "APIC-cookie=" +  resp.cookies["APIC-cookie"]}
+
+# Now we make a call towards the tenant class on the ACI fabric with the proper header value set.
+# We leverage the .xml ending to receive the data back as XML.  We're adding health and faults to the printout to ensure that we get levels of data back from the APIC
+tenants = requests.get("https://sandboxapicdc.cisco.com/api/node/class/fvTenant.json?rsp-subtree-include=health,faults", headers=header, verify=False)
+
+# Requests stores the text of the response in the .text attribute.  Lets print it to see raw JSON
+print(tenants.text)
+```
+There is a lot of manipulation going on with the top part of this script, but most of it deals with the methods needed to authenticate towards the ACI fabric, needing a username and password to authenticate, receive the response from the fabric and gather a token, then send this token in a subsequent call to the fabric to pull the ACI tenant information out in JSON format.  However, this snippet:
+
+  - imported the `request` library to easily interact with the ACI fabric's REST APIs
+  - constructed a call to authenticate against the APIC and store the authentication token as a cookie to be used later
+  - created a request to ask for all configured tenants in the fabric using the stored authentication cookie
+  - accessed the response from the query and printed the raw JSON output to the console/terminal  <br>
+
+4. Save the `get-tenant-json.py` file. To download or review the current code, you can get it from GitHub [here](https://github.com/CiscoDevNet/coding-skills-sample-code/blob/master/coding202-parsing-json/get-tenant-json-1.py).
+
+5. Open a command prompt.<br>
+  <br>
+  For Windows, enter:
+
+  ```
+  cd %USERPROFILE%\Desktop
+  ```
+
+  For OS X, enter:
+
+  ```
+  cd ~/Desktop
+  ```
+
+6. In the command prompt window, enter:
+
+  ```
+  python get-tenant-json.py
+  ```
+
+7. The command line/terminal displays the JSON data retrieved by the script.
+
+![](assets/images/json-output-new.png)
+
+--------------------------------------------------------------------------------
+
+This presentation of the JSON data isn't very useful. Next, clean up the presentation to get a better view of the structure and content of the data.
+
+**Next step:** Proceed to Step 2: Use the JSON Python library.

labs/parsing-json/2.md

@@ -0,0 +1,91 @@
+## Step 2: Use the JSON Python library
+
+### Use Python's JSON object
+
+The large JSON result you got in the previous step is a string. It has no special properties beyond that. To parse it, you would parse it as a string. However, Python comes with a standard `json` library for encoding/decoding and accessing JSON content. This library uses patterns that are familiar to Python developers. When you load a string using the `json` decoder, it converts JSON objects into Python [dictionaries](https://docs.python.org/3.4/reference/expressions.html#dictionary-displays) and JSON arrays into Python [lists](https://docs.python.org/3.4/reference/expressions.html#list-displays). This is useful because it then enables you to access and iterate through JSON as Python data.
+
+Another useful tool of the JSON library is it's ability to "pretty print" the JSON output into a hierarchical structure. This makes it easier to see the overall structure of the data. Now, use that capability to print the data into a more human-readable output.
+
+> **Note**: The `requests` library has the ability to return the data from the query in JSON without any additional lines of code, however, in this lab we will not be using this ability in order to understand how the `json` library works within Python. 
+
+1. Normally, we'd need to odify the second line of `get-tenant-json.py` to import the JSON library, however, due to the construct of the ACI authentication, we've already imported it.  You can verify that this line is present in the file:
+
+  ```
+  import json
+  ```
+
+2. Comment out the `print(tenants.text)` line by putting a pound or hash sign at the front of the line:
+
+  ```
+  # print(tenants.text)
+  ```
+  You are commenting out this line because you are going to use the `json` library to pretty print your output.  
+
+3. Update `get-tenant-json.py` by adding the following line below `#print(tenants.text)`:
+
+  ```
+  json_response = json.loads(tenants.text)
+  ```
+
+  The `json.loads()` method loads the `tenants.text` into a JSON object. If it is successful, you can use  square brackets to get a particular element from `json_response`.
+
+4. Add the following line just below the previous line you added:
+
+  ```
+  print(json.dumps(json_response, sort_keys=True, indent=4))
+  ```
+
+  This line prints the elements `dumps()` method returns from the `json_response`. The arguments control how the output is displayed.
+
+5. Save the `get-tenant-json.py` file. To download or review the current code, you can get it from GitHub [here](https://github.com/CiscoDevNet/coding-skills-sample-code/blob/master/coding202-parsing-json/get-tenant-json-2.py).
+
+6. To run your newly created file, enter:
+
+  ```
+  python get-tenant-json.py
+  ```
+
+7. The Python script gets and displays the following JSON data.
+
+![](assets/images/json-output-pretty-new.png)
+
+--------------------------------------------------------------------------------
+
+The content and structure of this data is easier for you to read and understand.
+
+### Understanding the returned JSON data
+
+Because you are getting JSON data, the content you get back has a particular order or schema. Elements of the returned 'fv-Tenant' ACI Managed Object (MO) class parsed in JSON data have sub-objects and even sub-dictionaries and sub-lists. For this exercise, you are interested in the **name**, **dn**, and **health** of each of the tenants configured within the fabric. This approach returns the desired information, as well as additional bits returned as part of the query to the `fv-Tenant` class.
+
+```
+{fvTenant}
+  {attributes}
+  annotation
+  childAction
+  descr
+  dn
+  extMngdBy
+  lcOwn
+  modTs
+  monPolDn
+  name
+  nameAlias
+  ownerKey
+  ownerTag
+  status
+  uid
+  {children}
+    {healthInst}
+      {attributes}
+      ...
+      ...
+...
+```
+
+In the example shown, `fvTenant` is dictionary of multiple tenant objects - each with their `name`, `dn`, and other attributes.
+
+Now that you have seen this structure, go to the next step and learn how to get only the data you care about.
+
+**Next step:**
+
+Proceed to Step 3: Iterate through a JSON dictionary in Python.

labs/parsing-json/3.md

@@ -0,0 +1,53 @@
+## Step 3: Iterate through a JSON dictionary in Python
+
+### Loop through a Python dictionary
+
+In the previous step, you decoded the JSON content into a `json_response` variable.  This conversion allows a developer to easily access the information contained within using loops to iterate through the data.  Using this method, we will loop through the tenants, print their name, DN, and their health score.
+
+To loop through the tenants within a dictionary, first get the tenants using the `json` library. Then, use a Python `for` loop to go through each element of the list.  A second loop won't be required, as the list contained within the `children` element returned only contains a single value, `healthInst`.
+
+Keep in mind that you may need to reference the pretty-print JSON that we created in the previous section, focusing on a single tenant within the output, in order to iterate through the object correctly.  You can also run the script from the previous section in "interactive" mode using `python -i`, which will allow you to interact with the stored variables to determine what the nested types are and how to access different elements to get to the desired key-value pairs in the JSON.
+
+> **Note**: this looks like a lot of manipulation and parsing, but it will provide a very good testbed to understand how to iterate through JSON
+
+1. Preserving the indentation, comment out the previous print statement (wherein we printed the "pretty" JSON) and add the following lines:
+
+  ```python
+json_tenants = json_response['imdata']
+for tenant in json_tenants:
+    tenant_name = tenant['fvTenant']['attributes']['name']
+    tenant_dn = tenant['fvTenant']['attributes']['dn']
+    tenant_health = tenant['fvTenant']['children'][0]['healthInst']['attributes']['cur']
+    output = "Tenant: " + tenant_name + "\t Health Score: " + tenant_health + "\n DN: " + tenant_dn
+    print(output.expandtabs(40))
+  ```
+
+  This snippet:
+
+  - Starts the initial entry point inside of the `imdata` dictionary
+  - Creates a `for` loop to iterate through the list of `fvTenant` objects sequentially
+  - Gathers the `name` and `dn` values within the `attributes` dictionary contained within the `fvTenant` dictionary
+  - Gathers the current health score by pulling the value from the `children` dictionary.  This is pulled from the list of child objects (there's only a single item, which is why this can be safely set to `0`), and then moving through the `healthInst` dictionary, followed by the `attributes` dictionary and pulling the value from `cur`
+  - Prints the resulting data with nice formatting, using the `expandtabs` method.  If the resulting printed data is not aligned, increase this value to 50 or so (results will vary due to length of configured tenant names on the fabric at any one time)
+
+2. Save the `get-tenant-json.py` file.  To download or review the current code, you can get it from GitHub [here](https://github.com/CiscoDevNet/coding-skills-sample-code/blob/master/coding202-parsing-json/get-tenant-json-3.py)
+
+3. Enter the following command to run your file.
+
+  ```
+  python get-tenant-json.py
+  ```
+
+4. When you run the Python script, at the end of the output, you should get the JSON data values returned for each tenant in a format that looks similar to this:
+
+![](assets/images/json-output-parse-001-new.png)
+
+--------------------------------------------------------------------------------
+
+This is a very direct way to use Python to get data from a REST service using JSON and parse out only the information you care about. Depending on the capabilities of the REST API, you can also sometimes pass in query parameters or other information to reduce the scope of returned data or search for a single or group of specific items.
+
+For a summary of resources, continue on to the last step.
+
+**Next step:**
+
+Proceed to Step 4: Find additional resources.

labs/parsing-json/4.md

@@ -0,0 +1,27 @@
+## Step 4: Find additional resources
+
+For more information on the topics covered, visit the following resources.
+
+### JavaScript Object Notation (JSON)
+
+For more information on JavaScript Object Notation (JSON), visit [https://www.json.org/](https://www.json.org/ "JSON.org").
+
+Also consider visiting the JavaScript Object Notation (JSON) tutorials at [https://www.w3schools.com/js/js_json_intro.asp](https://www.w3schools.com/js/js_json_intro.asp "W3Schools JSON")
+
+### Python
+
+Python is a powerful tool. To learn more, visit [https://docs.python.org/3.4/tutorial/](https://docs.python.org/3.4/tutorial/ "Python Tutorial").
+
+**Python JSON Libraries**<br>
+The documentation for the JSON Python library can be found at [https://docs.python.org/3.4/library/json.html](https://docs.python.org/3.4/library/json.html "Python JSON").
+
+### Application Centric Infrastructure
+
+**Product Information**<br/>
+[https://www.cisco.com/c/en/us/solutions/data-center-virtualization/application-centric-infrastructure/index.html](https://www.cisco.com/c/en/us/solutions/data-center-virtualization/application-centric-infrastructure/index.html "Application Centric Infrastructure (ACI) Product Site")
+
+**Developer Resources**<br/>
+[https://developer.cisco.com/site/aci/](https://developer.cisco.com/site/aci/ "Application Centric Infrastructure Developer Site")
+
+**Application Centric Infrastructure (ACI) API Documentation**<br/>
+[https://developer.cisco.com/docs/aci/](https://developer.cisco.com/docs/aci/ "ACI API Documentation")