You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1 line
21 KiB
1 line
21 KiB
{"cells": [{"cell_type": "markdown", "id": "1", "metadata": {}, "source": ["<!--\n", "title: Modules and Libraries\n", "type: lesson\n", "duration: \"00:45\"\n", "-->\n", "\n", "##  {.separator}\n", "\n", "<h1>Introduction to APIs</h1>\n", "\n", "\n", "<!--\n", "\n", "## Overview\n", "This lesson walks through the idea of application programming interfaces (APIs), starting with their definition. It touches on JSON versus XML, followed by a series of exercises that introduce keys and parameters.\n", "\n", "## Learning Objectives\n", "In this lesson, students will:\n", "\n", "- Describe what an application programming interface (API) is and why we might use one.\n", "- Identify common APIs on the web.\n", "- Call an API.\n", "\n", "\n", "\n", "## Duration\n", "45 minutes\n", "\n", "#### Timing Notes:\n", "This is the last lesson of the last unit of core Python material; after this is the unit lab. The slides as laid out here are quite short, designed to allow a lot of flex time for you to add exercises on any topics the students have struggled with (of note, `hw-10wk-9` has much more API practice).\n", "\n", "Address any remaining questions in the parking lot here.\n", "\n", "\n", "## Suggested Agenda\n", "\n", "| Time | Activity |\n", "| --- | --- |\n", "| 0:00 - 0:03 | Welcome |\n", "| 0:03 - 0:10 | API Overview |\n", "| 0:11 - 0:42 | Calling APIs |\n", "| 0:42 - 0:45 | Summary |\n", "\n", "## Differentiation and Extensions\n", "- For more advanced students, have them call other APIs (refer back to the early slide with the list) and print out the information for that legibly.\n", "- Have them look through the jsonplaceholder API and print out even more information.\n", "- Fill extra time by chaining together exercises on everything they've learned.\n", "\n", "## In Class: Materials\n", "- Projector\n", "- Internet connection\n", "- Python 3\n", "-->\n", "\n", "---\n", "\n", "## Lesson Objectives\n", "\n", "*After this lesson, you will be able to\u2026*\n", "\n", "- Describe what an application programming interface (API) is and why we might use one.\n", "- Identify common APIs on the web.\n", "- Call an API.\n", "\n", "---\n", "\n", "## Discussion: Web Magic\n", "\n", "Have you seen\u2026\n", "\n", "- A website with Google Maps on the page (like Yelp)?\n", "- A program that had live stock market info?\n", "- A website that isn't Twitter but shows a live Twitter feed?\n", "- Any app that pulls info from somewhere else?\n", "\n", "How did they do this?\n", "\n", "\n", "\n", "\n", "<aside class=\"notes\">\n", "\n", "**Talking Points:**\n", "\n", "- Give examples here, like\u2026\n", "- Have you seen a website that had a Google Map on it like Yelp? Yelp's developers _didn't_ build that map themselves, as it was created by Google. What if you want a Google Map embedded in your web app to show people where they can visit you? You aren't going to make that map yourself, so somehow you have to call Google. Well, Google has a way you can get that map information \u2014 all you have to do is send a request to the URL that Google provides, and it gives you back a map you can use.\n", "\n", "**Teaching Tips:**\n", "\n", "- Get students discussing.\n", "- Terminology note: Google Maps is *embedded* on the page.\n", "\n", "</aside>\n", "\n", "---\n", "\n", "## APIs (Application Program Interfaces)\n", "\n", "An API is a service that provides raw data for public use.\n", "\n", "APIs give us data, maps, anything!\n", "\n", "| What's the API? | Sample URL \u2014 put this in a new tab! |\n", "|------|------------|\n", "| **<a href=\"http://swapi.co/api/people/3\" target=\"_blank\">The Star Wars API: Request R2-D2 info</a>** | http://swapi.co/api/people/3 |\n", "| **<a href=\"http://dev.markitondemand.com/Api/Quote/xml?symbol=AAPL\" target=\"_blank\">Markit Digital's API: Request current Apple stock info</a>** | http://dev.markitondemand.com/Api/Quote/xml?symbol=AAPL |\n", "| **<a href=\"https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22\" target=\"_blank\">OpenWeatherMap: The current weather in London</a>** | https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22 |\n", "\n", "Do you think you've been on websites that call an API?\n", "\n", "> Does the JSON look unreadable in the browser? If you're using Chrome, install the [JSONView plugin](https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en).\n", "\n", "\n", "<aside class=\"notes\">\n", "\n", "**Teaching Tips:**\n", "\n", "- Open each of these URLs in a new window so students can see what happens when you call an API.\n", "- Encourage a discussion if students can think of other APIs.\n", "\n", "**Talking Points:**\n", "\n", "- Basically, an API is a service that provides raw data for public use. As third-party software developers, we can access an organization's API and use its data within our own applications. The term now commonly refers to web URLs that can be accessed for raw data.\n", "- Why recreate data when we don't have to? Think about past projects or ideas that would be easier if you could pull in data already gathered elsewhere.\n", "- APIs can provide us with data that we would otherwise not be able to create ourselves.\n", "- There are a variety of APIs available on the internet. To call an API, send a request to a URL and that API will return data to your program. You can pull data from anywhere that offers an API.\n", "- You can make this request as specific as you'd like \u2014 each web app out there offers different options for its API. You just have to find out what you can request!\n", "- Here are just a few examples of APIs you can use. Check it out \u2014 the left column is the common name you might know. The right column is the URL to which you, in your program, would send a request. You can click those URLs to see what each call would return.\n", "\n", "</aside>\n", "\n", "---\n", "\n", "## How Do We Use an API?\n", "\n", "We'll use the `requests` module.\n", "\n"]}, {"cell_type": "code", "id": "2", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "3", "metadata": {}, "source": ["\n", "This works, but there's one very helpful line missing!\n", "\n", "Before we see this in action, let's look at what the API might return.\n", "\n", "<aside class=\"notes\">\n", "\n", "**Teaching Tip:**\n", "\n", "- Go down the code here \u2014 be sure students understand the idea.\n", "\n", "**Talking Point:**\n", "\n", "- We're going to demo this and write this code soon! But first, we need to see what the API might give us back.\n", "\n", "</aside>\n", "\n", "---\n", "\n", "## JSON vs. XML\n", "\n", "\n", "Imagine: You write code for a list.\n", "\n"]}, {"cell_type": "code", "id": "4", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "5", "metadata": {}, "source": ["\n", "But then, `my_list` is unexpectedly a dictionary, or an int, or even a class! The code we wrote won't work.\n", "\n", "APIs can give data back in two ways: JSON or XML. Depending on what the API does, we need to write our program a different way.\n", "\n", "\n", "<aside class=\"notes\">\n", "\n", "**Teaching Tips:**\n", "\n", "- Go down the code here \u2014 be sure students understand the idea.\n", "\n", "**Talking Point:**\n", "\n", "- We're going to demo this and write this code soon! But first, we need to see what the API might give us back.\n", "\n", "</aside>\n", "\n", "---\n", "\n", "## How Do APIs Give Us Info? Option 1: JSON\n", "\n", "\n", "Here's a potential return from an API:\n", "\n"]}, {"cell_type": "code", "id": "6", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "7", "metadata": {}, "source": ["\n", "Looks like a dictionary with a list of dictionaries inside it, right?\n", "\n", "But it's not a dictionary! It's **JSON** (JavaScript Object Notation).\n", "\n", "The `requests` module has a [built-in JSON decoder](http://docs.python-requests.org/en/master/user/quickstart/#json-response-content) to turn JSON into a Python dictionary.\n", "\n", "We can **decode** JSON with `decoded_data = response_from_request.json()`.\n", "\n", "\n", "<aside class=\"notes\">\n", "\n", "**Talking Points:**\n", "\n", "- So, APIs are great\u2026 What does it look like?\n", "- **JSON** stands for \"JavaScript Object Notation\" and has become a universal standard for serializing native data structures for transmission. It is lightweight, easy to read, and quick to parse. JSON looks like this \u2014 it's easily readable and information is separated with braces (`{}`) and commas.\n", "\n", "</aside>\n", "\n", "---\n", "\n", "## How Do APIs Give Us Info? Option 2: XML\n", "\n", "Instead of JSON, we might get XML:\n", "\n"]}, {"cell_type": "code", "id": "8", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "9", "metadata": {}, "source": ["\n", "JSON is certainly easier to read!\n", "\n", "- We'll stick with JSON whenever we can.\n", "\n", "> **Pro tip:** Most of you don't need to know about XML, but if you're working with legacy code or an older API, you may have to use it. In that case, look up [Element Tree XML](https://python.readthedocs.io/en/stable/library/xml.etree.elementtree.html).\n", "\n", "\n", "<aside class=\"notes\">\n", "\n", "**Talking Points:**\n", "\n", "- **XML**, which stands for \"Extensible Markup Language,\" is one of the first serialized data formats (itself based on HTML). XML is messy and cumbersome to parse, but remains a major format because of its legacy usage across the web.\n", "- Conveniently, many APIs publish data in multiple formats and let you specify which you'd like. For example,\n", "`https:///api/index.php?output=json` or `https:///api/index.php?output=xml`.\n", "- We'll be using JSON.\n", "\n", "</aside>\n", "\n", "---\n", "\n", "## Let's Choose an API\n", "\n", "**To recap:** APIs give us data we can use in either XML or JSON.\n", "\n", "Let's call one!\n", "\n", "Check out <a href=\"http://api.open-notify.org/astros.json\" target=\"\\_blank\">http://api.open-notify.org/astros.json</a>, which tells us the people currently aboard the International Space Station (ISS).\n", "\n"]}, {"cell_type": "code", "id": "10", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "11", "metadata": {}, "source": ["\n", "\n", "<aside class=\"notes\">\n", "\n", "**Teaching Tips:**\n", "\n", "- The number of astronauts and names currently aboard the International Space Station (ISS).\n", "- Go to the website in the browser so that students can see what it returns.\n", "- Ask if it's JSON or XML to check their memory.\n", "\n", "</aside>\n", "\n", "\n", "---\n", "\n", "## Calling an API\n", "\n", "- Import the `request` module.\n", "- Call the API (`requests.get()`).\n", "- Parse the response with `response.json()`.\n", "\n", "<iframe height=\"400px\" width=\"100%\" src=\"https://repl.it/@GAcoding/python-programming-apis-iss?lite=true\" scrolling=\"no\" frameborder=\"no\" allowtransparency=\"true\" allowfullscreen=\"true\" sandbox=\"allow-forms allow-pointer-lock allow-popups allow-same-origin allow-scripts allow-modals\"></iframe>\n", "\n", "\n", "<aside class=\"notes\">\n", "\n", "**Teaching Tips:**\n", "\n", "- Go down this code line by line. Why do we import these modules? What does each line do? Where do `.read` and `.loads` come from?\n", "- Terminology: parse.\n", "\n", "**Repl.it note:**\n", "\n"]}, {"cell_type": "code", "id": "12", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "13", "metadata": {}, "source": ["</aside>\n", "\n", "---\n", "\n", "## You Do: Calling an API\n", "\n", "Open a new file, `my_api.py`. Type and run the code:\n", "\n"]}, {"cell_type": "code", "id": "14", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "15", "metadata": {}, "source": ["\n", "\n", "<aside class=\"notes\">\n", "\n", "**Teaching Tips:**\n", "\n", "- It's the same code to get them used to typing it with an expected output. Discourage copying anything but the URL.\n", "- Walk around to be sure everyone can do it.\n", "</aside>\n", "\n", "---\n", "\n", "## We Do: A New API\n", "\n", "Awesome! Go back to your file. Let's instead call this URL:\n", "\n", "`http://dev.markitondemand.com/Api/Quote/xml?symbol=AAPL`\n", "\n", "Why does it break? We can't parse XML like JSON.\n", "\n"]}, {"cell_type": "code", "id": "16", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "17", "metadata": {}, "source": ["\n", "\n", "<aside class=\"notes\">\n", "\n", "**Teaching Tips:**\n", "\n", "- Do this with them!\n", "- This is just a quick aside \u2014 the next slide is back to JSON.\n", "\n", "**Talking Point:**\n", "\n", "- XML is out of the scope of our class. But, if your API errors, check that you're correctly parsing XML or JSON. We'll go back to JSON now.\n", "</aside>\n", "\n", "---\n", "\n", "## Quick Review\n", "\n", "We've called an API! Great job. We did this with the `get()` function in the `requests` module. APIs are made available by other websites or applications. They give us data we can use in either XML or JSON.\n", "\n"]}, {"cell_type": "code", "id": "18", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "19", "metadata": {}, "source": ["\n", "\n", "JSON:\n", "\n"]}, {"cell_type": "code", "id": "20", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "21", "metadata": {}, "source": ["\n", "---\n", "\n", "## Quick Review\n", "\n", "XML:\n", "\n"]}, {"cell_type": "code", "id": "22", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "23", "metadata": {}, "source": ["\n", "\n", "---\n", "\n", "## You Do: Back to JSON\n", "\n", "Back in your file, change the API call back to `http://api.open-notify.org/astros.json`.\n", "\n", "Once it's decoded, it's a dictionary!\n", "\n", "Replace your `print` statement:\n", "\n"]}, {"cell_type": "code", "id": "24", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "25", "metadata": {}, "source": ["\n", "Can we go further? Try to only print the `name`s of the astronauts.\n", "\n", "\n", "<aside class=\"notes\">\n", "5 MINUTES\n", "\n", "**Teaching Tip:**\n", "\n", "- Walk through printing the original output again, but give students a few minutes to try to print only the names before showing the answer on the next slide.\n", "</aside>\n", "\n", "---\n", "\n", "## Name Printing: Solution\n", "\n", "Working backward, we have a:\n", "\n", "- Dictionary (key: `name`).\n", "- Which is inside a list (the value of `people`).\n", "- Which is inside a dictionary (key: `people`).\n", "\n"]}, {"cell_type": "code", "id": "26", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "27", "metadata": {}, "source": ["\n"]}, {"cell_type": "code", "id": "28", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "29", "metadata": {}, "source": ["\n", "\n", "<aside class=\"notes\">\n", "\n", "**Teaching Tips:**\n", "\n", "- Walk through this with the students.\n", "- Show the code!\n", "</aside>\n", "\n", "\n", "---\n", "\n", "## You Do: Shakespeare\n", "\n", "In your file, call the Shakespeare API `http://ShakeItSpeare.com/api/poem`.\n", "\n", "Print only the poem.\n", "\n", "\n", "<aside class=\"notes\">\n", "\n", "3 MINUTES\n", "\n", "**Teaching Tip:**\n", "\n", "- Give students a few minutes to try to print only the poem before showing the answer on the next slide.\n", "</aside>\n", "\n", "---\n", "\n", "## Shakespeare: Solution\n", "\n", "Print only the poem.\n", "\n"]}, {"cell_type": "code", "id": "30", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "31", "metadata": {}, "source": ["\n", "\n", "<aside class=\"notes\">\n", "\n", "**Teaching Tips:**\n", "\n", "- Walk through this with them.\n", "- Show the code!\n", "</aside>\n", "\n", "---\n", "\n", "## Quick Review\n", "\n", "When we convert JSON, it keeps the same format, only in a Python structure.\n", "\n", "When parsing an API's return, look through the JSON to find the exact structure you need. Is it the string value from the `poem` key? Or the value from each `name` key in a list of dictionaries, which is the value of the `people` key?\n", "\n", "Think it through before writing your code.\n", "\n"]}, {"cell_type": "code", "id": "32", "metadata": {}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "33", "metadata": {}, "source": ["\n", "<aside class=\"notes\">\n", "\n", "**Teaching Tip:**\n", "\n", "- Do a quick check for understanding.\n", "\n", "</aside>\n", "\n", "\n", "---\n", "\n", "## I Do: API Authentication\n", "\n", "\n", "Many APIs are free but require a **key**. This identifies the developer requesting access.\n", "\n", "If we call the Giphy API:\n", "\n", "- With no key, `http://api.giphy.com/v1/gifs/search?q=funny+cat`, we get `Error - Unauthorized`!\n", "\n", "- With a key, `http://api.giphy.com/v1/gifs/search?q=funny+cat&api_key=dc6zaTOxFJmzC`, it works!\n", "\n", "---\n", "\n", "## I Do: API Authentication\n", "\n", "Syntax Notes:\n", "\n", "- The main API URL is `http://api.giphy.com/v1/gifs/search`.\n", "- `?` always delineates a URL and its parameters.\n", " - (The `?` is a standard for every URL! Searching Google for \"banana,\" with `q` short for \"query:\" `https://www.google.com/search?q=banana`).\n", " - (Here's another one! Searching Amazon for \"banana:\" `https://www.amazon.com/s?field-keywords=banana`.)\n", "\n", "**Most importantly**, never publish your key for a backend service, including on GitHub! (This is an example.) There are other ways to provide your key to a server in order to keep that key safe. However, if your code is using JavaScript, that's ok as that provides only read access in general (assuming you have your permissions properly configured.) This is a sticking point for developers coming to Python from a front-end perspective.\n", "\n", "<aside class=\"notes\">\n", "\n", "**Teaching Tips:**\n", "\n", "- Syntax is called out here for the first time. Continue calling it out throughout the rest of the lesson. Stress that every API has different parameters \u2014 read the docs!\n", "- Show this in a browser.\n", "\n", "**Talking Points:**\n", "\n", "- While the majority of APIs are free to use, many of them require an API \"key\" that identifies the developer requesting data access.\n", "- This is done to regulate usage and prevent abuse. Some APIs also rate-limit developers, meaning they have caps on the free data allowed during a given time period.\n", "- Some APIs, such as Spotify's music catalog, might seem like they should be available for anyone to access, but imagine if PayPal had an API from which shops could request your money. Now, imagine Etsy calls PayPal when you buy something. You'd want Etsy to have to prove it was actually Etsy, right? You don't want anyone to be able to pretend to be Etsy, go to PayPal, and charge you $500. Instead, you'd want Etsy to somehow authenticate to PayPal.\n", "- This is accomplished by giving Etsy a private key to use at PayPal that only Etsy knows. Every time Etsy makes a request to PayPal, Etsy can say, \"Hey, I'm requesting this. Here is my proof that I'm allowed to do so.\"\n", "- When you are calling APIs that require a key, it's up to you to store those keys somewhere private. They are the only proof that you are you and you are allowed to call that API, after all.\n", "\n", "\n", "</aside>\n", "\n", "---\n", "\n", "\n", "## You Do: JSONPlaceholder API\n", "\n", "Read about the API <a href=\"https://jsonplaceholder.typicode.com/\" target=\"\\_blank\">here</a>.\n", "\n", "Call this URL: https://jsonplaceholder.typicode.com/users/1 .\n", "\n", "- Display the name, username, email and phone that came back from the API.\n", "\n", "<aside class=\"notes\">\n", "\n", "5-10 MINUTES\n", "\n", "**Teaching Tips:**\n", "\n", "- Give students five or 10 minutes \u2014 encourage them to look through the API result. If students look lost, run this as a We Do and open the API call with them. It's not a quiz \u2014 it's just to get their brains thinking.\n", "\n", "</aside>\n", "\n", "---\n", "\n", "## JSONPlaceholder API Solution\n", "\n", "<iframe height=\"400px\" width=\"100%\" src=\"https://repl.it/@GAcoding/unit-5-apis-placeholder-solution?lite=true\" scrolling=\"no\" frameborder=\"no\" allowtransparency=\"true\" allowfullscreen=\"true\" sandbox=\"allow-forms allow-pointer-lock allow-popups allow-same-origin allow-scripts allow-modals\"></iframe>\n", "---\n", "\n", "## Summary\n", "\n", "APIs:\n", "\n", "- Handy URLs from which we can get information.\n", "- Sometimes require keys.\n", "- Usually free.\n", "- Call with the `requests()` module.\n", "\n", "XML and JSON:\n", "\n", "- Two formats in which APIs might return information to us.\n", "- XML is legacy.\n", "- JSON looks like a dictionary.\n", "\n", "---\n", "\n", "\n", "## Additional Resources\n", "\n", "- Here's an example of a [stolen key horror story](https://wptavern.com/ryan-hellyers-aws-nightmare-leaked-access-keys-result-in-a-6000-bill-overnight).\n", "- The [Programmable Web API Directory](http://www.programmableweb.com/apis/directory)\n", "- [Element Tree XML](https://python.readthedocs.io/en/stable/library/xml.etree.elementtree.html)\n"]}], "metadata": {"kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"}, "language_info": {"codemirror_mode": {"name": "ipython", "version": 3}, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.7.6"}}, "nbformat": 4, "nbformat_minor": 5} |