Update APIs lesson

Author: pletcher

10_apis.ipynb

@@ -146,7 +146,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Reading responses"
+    "## Reading responses\n",
+    "\n",
+    "As you can see above, the response returns a JSON (JavaScript Object Notation) object with a few top-level keys. If you're thinking, \"Hm, this JSON looks an awful lot like a Python dictionary,\" you're absolutely right. While the semantics of Python dictionaries and JSON _are_ different, in this case, the `requests` library has already coerced the raw JSON to a Python dictionary for us. You can access its values like you would with any Python dict:"
    ]
   },
   {
@@ -155,14 +157,27 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Reading responses"
+    "parsed_response = response.json()\n",
+    "\n",
+    "parsed_response['count']"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    ":::{important}\n",
+    "Experiment a bit. How, for example, would you get all of the titles in a list?\n",
+    ":::"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Constructing queries"
+    "## Constructing queries\n",
+    "\n",
+    "Naturally, when you're working with an API, you'll want to be able to construct your own queries. Above, we hard-coded the value `weasels` under the querystring parameter `q`. But you can use Python's string interpolation to set any value you want. For example"
    ]
   },
   {
@@ -171,7 +186,61 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Constructing queries"
+    "my_query = \"foxes\"\n",
+    "my_url = f\"https://api.dp.la/v2/items?q={my_query}&api_key={DPLA_API_KEY}\"\n",
+    "\n",
+    "response = requests.get(my_url)\n",
+    "\n",
+    "parsed_response = response.json()\n",
+    "parsed_response"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You could even write a function that puts constructs the request URL and returns the parsed response so that you don't have to do these things manually over and over again."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def make_dpla_request(query: str):\n",
+    "    url = f\"https://api.dp.la/v2/items?q={query}&api_key={DPLA_API_KEY}\"\n",
+    "    response = requests.get(url)\n",
+    "\n",
+    "    return response.json()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "There's a problem with this code, however. What happens if you try to make a request with a query that contains spaces, such as `\"red foxes\"`?\n",
+    "\n",
+    "Can you find the appropriate workaround using the documentation? https://pro.dp.la/developers/requests\n",
+    "\n",
+    "What other features does this API support?"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## RESTful APIs\n",
+    "\n",
+    "Many APIs, including the DPLA's, are built on RESTful principles. REST stands for **Re**presentational **S**tate **T**ransfer. In terms of web APIs, REST means that a given server will respond with a representation of the data that it has available, and that representation will contain additional information for manipulating the data or requesting further data.\n",
+    "\n",
+    "Although it is not, strictly speaking, a requirement of REST APIs, many REST implementations use a predictable URL scheme.\n",
+    "\n",
+    "For example, you might find a list of \"collections\" at the `/collections` endpoint. To request a specific collection, you would append its ID — e.g., for Collection 3, `/collections/3`.\n",
+    "\n",
+    "Each collection might contain items, so to get a list of items in Collection 3 you could send a request to `/collections/3/items`. And then to get a specific item in that collection — you guessed it, `/collections/3/items/12`.\n",
+    "\n",
+    "DPLA does _not_ implement this kind of schema, and instead relies on facets and other search parameters. But it is worth being aware of such schemes if you want to use other APIs in your work and research."
    ]
   },
   {