Merge pull request #245 from teemu-ruokolainen/web_api_narrative

web api: add narrative

Author: rkdarst

content/web-apis.ipynb

@@ -68,7 +68,7 @@
     "# Embed the requests homepage\n",
     "from IPython.display import IFrame\n",
     "requests_documentation_url = \"https://requests.readthedocs.io/en/latest/\"\n",
-    "IFrame(requests_documentation_url, 1000,300)"
+    "IFrame(requests_documentation_url, '100%', '30%')"
    ]
   },
   {
@@ -80,43 +80,7 @@
     "\n",
     "An **API (Application Programming Interface)** is the definition of the way computer programs communicate with each other.  We use Requests to connect to the API of a web server, tell it what we want, and it returns it to us.  This is called the **request-response** cycle.\n",
     "\n",
-    "We can find a list of some free APIs (available without authentication) at <https://apipheny.io/free-api/#apis-without-key> ."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 2,
-   "id": "9f523046-6426-4c5d-b312-297e82165481",
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/html": [
-       "\n",
-       "        <iframe\n",
-       "            width=\"1000\"\n",
-       "            height=\"500\"\n",
-       "            src=\"https://apipheny.io/free-api/#apis-without-key\"\n",
-       "            frameborder=\"0\"\n",
-       "            allowfullscreen\n",
-       "            \n",
-       "        ></iframe>\n",
-       "        "
-      ],
-      "text/plain": [
-       "<IPython.lib.display.IFrame at 0x7f6bfc5dc7f0>"
-      ]
-     },
-     "execution_count": 2,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "# Embed apipheny.io (has a list of free APIs)\n",
-    "from IPython.display import IFrame\n",
-    "free_apis_url = \"https://apipheny.io/free-api/#apis-without-key\"\n",
-    "IFrame(free_apis_url, 1000,500)"
+    "We can find a list of some free APIs (available without authentication) at <https://apipheny.io/free-api/#apis-without-key> . These APIs can be used for developing and testing our code."
    ]
   },
   {
@@ -131,7 +95,9 @@
     "* **GET** is the type of request we make and\n",
     "* `/fact` is the **path**.\n",
     "\n",
-    "You can even test this in your web browser: <https://catfact.ninja/fact>"
+    "You can even test this in your web browser: <https://catfact.ninja/fact>\n",
+    "\n",
+    "Using the Requests library, we do this with {meth}`~requests.get`."
    ]
   },
   {
@@ -912,41 +878,19 @@
    "source": [
     "## After exercises: Saving retrieved data to disk\n",
     "\n",
-    "To save the retrieved JSON objects to disk, it is practical to use the JSONLINES file format. The JSONLINES format contains a single valid JSON object on each line.\n",
+    "Usually, we want to save the retrieved data to disk for later use. For example, we might collect data for one year and later analyze it for a longitudal study.\n",
+    "\n",
+    "To save the retrieved JSON objects to disk, it is practical to use the JSONLINES file format. The JSONLINES format contains a single valid JSON object on each line. This is preferable to saving each object as its own file since we don't, in general, want to end up with excessive amounts of individual files (say, hundreds of thousands or millions).\n",
     "\n",
     "For example, let's retrieve three cat facts and save them to a JSONLINES file using the [jsonlines library](https://jsonlines.readthedocs.io/en/latest/)."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 23,
-   "id": "6eccc88a-e3dd-4756-8ef6-d93f98bd5dc3",
+   "id": "80a8dcd1-ba04-45de-840e-aa014c19a75c",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Make request 0\n",
-      "Make request 1\n",
-      "Make request 2\n"
-     ]
-    },
-    {
-     "data": {
-      "text/plain": [
-       "[{'fact': 'A cat has 230 bones in its body. A human has 206. A cat has no collarbone, so it can fit through any opening the size of its head.',\n",
-       "  'length': 130},\n",
-       " {'fact': 'The most popular pedigreed cat is the Persian cat, followed by the Main Coon cat and the Siamese cat.',\n",
-       "  'length': 101},\n",
-       " {'fact': 'The average cat food meal is the equivalent to about five mice.',\n",
-       "  'length': 63}]"
-      ]
-     },
-     "metadata": {},
-     "output_type": "display_data"
-    }
-   ],
+   "outputs": [],
    "source": [
     "# Import\n",
     "import jsonlines\n",
@@ -979,8 +923,48 @@
     "with jsonlines.open('catfacts.jsonl', mode='w') as writer:\n",
     "\n",
     "    # Write\n",
-    "    writer.write(response_jsons)\n",
-    "    \n",
+    "    writer.write(response_jsons)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "efb4a0ff-6a70-471a-af61-39c0350d4166",
+   "metadata": {},
+   "source": [
+    "We can then read the objects from the disk using the same library."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 23,
+   "id": "2d424c23-bdf3-47f7-a643-4312a07c955a",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Make request 0\n",
+      "Make request 1\n",
+      "Make request 2\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "[{'fact': 'A cat has 230 bones in its body. A human has 206. A cat has no collarbone, so it can fit through any opening the size of its head.',\n",
+       "  'length': 130},\n",
+       " {'fact': 'The most popular pedigreed cat is the Persian cat, followed by the Main Coon cat and the Siamese cat.',\n",
+       "  'length': 101},\n",
+       " {'fact': 'The average cat food meal is the equivalent to about five mice.',\n",
+       "  'length': 63}]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
     "# Open a jsonlines reader\n",
     "with jsonlines.open('catfacts.jsonl', mode='r') as reader:\n",
     "    \n",
@@ -991,7 +975,7 @@
     "assert response_jsons == jsons_from_file\n",
     "\n",
     "# Display the JSON objects read from file\n",
-    "display(jsons_from_file)\n"
+    "display(jsons_from_file)"
    ]
   },
   {

requirements.txt

@@ -10,3 +10,4 @@ sphinxext-opengraph
 
 # for web-apis execution
 jsonlines
+bs4