{ "cells": [ { "cell_type": "markdown", "id": "ch13-title", "metadata": {}, "source": [ "# APIs" ] }, { "cell_type": "markdown", "id": "ch13-overview", "metadata": {}, "source": [ "APIs let your code communicate with web services, data sources, and cloud tools.\n", "\n", "- REST APIs and HTTP methods\n", "- `requests.get()` and response objects\n", "- JSON data as Python dictionaries and lists\n", "- Query parameters and headers\n", "- Reliability patterns for errors, timeouts, pagination, and retries\n" ] }, { "cell_type": "markdown", "id": "1300-video", "metadata": {}, "source": [ "

Chapter Video

\n", "\n", "This overview introduces HTTP requests in Python, including reading JSON data from web responses.\n", "\n", "```{raw} html\n", "\n", "```\n", "\n", "> *[Python Requests Tutorial: Request Web Pages, Download Images, POST Data, Read JSON, and More (25:00)](https://youtube.com/watch?v=tb8gHvYlCFs) by Corey Schafer*\n", ">\n", "> Hosted on YouTube; property of its original creator, embedded here for educational reference only." ] }, { "cell_type": "markdown", "id": "ch13-goals", "metadata": {}, "source": [ "

Learning Objectives

\n", "\n", "By the end of this chapter, you will be able to:\n", "\n", "1. Explain what an API is and how REST APIs communicate over HTTP\n", "2. Make GET requests with `requests`, pass query parameters, and convert between JSON text and Python objects with `response.json()`, `json.loads()`, and `json.dumps()`\n", "3. Handle HTTP errors, timeouts, and invalid JSON without crashing your program\n", "4. Send POST requests with JSON bodies and authenticate with headers and API keys read from environment variables\n", "5. Parse nested JSON defensively and validate a response against the keys your code expects\n", "6. Collect paginated results and retry temporary failures with exponential backoff\n" ] }, { "cell_type": "markdown", "id": "ch13-flow", "metadata": {}, "source": [ "

Chapter Flow

\n", "\n", "```{container} chapter-flow\n", "1. {doc}`1201-apis`\n", "2. {doc}`1202-api-reliability`\n", "```" ] }, { "cell_type": "markdown", "id": "ch12-glossary", "metadata": {}, "source": [ "

Glossary

\n", "\n", "| # | Term | Explanation |\n", "|---:|---|---|\n", "| 1 | API | An application programming interface, a defined way for software systems to communicate. |\n", "| 2 | Web API | An API accessed over the web, usually with HTTP requests. |\n", "| 3 | HTTP | The protocol commonly used for web requests and responses. |\n", "| 4 | REST | An API design style that uses resources, URLs, and standard HTTP methods. |\n", "| 5 | Endpoint | A URL where a specific API resource or action is available. |\n", "| 6 | HTTP method | A request action such as GET, POST, PUT, PATCH, or DELETE. |\n", "| 7 | Status code | A numeric response code that summarizes whether an HTTP request succeeded or failed. |\n", "| 8 | GET request | An HTTP request used to retrieve data. |\n", "| 9 | POST request | An HTTP request commonly used to send new data to a server. |\n", "| 10 | Query parameter | A key-value option added to a URL to customize a request. |\n", "| 11 | URL encoding | Replacing special characters in a URL, such as spaces, `&`, and `=`, with `%` codes so values cannot break the query string. |\n", "| 12 | Header | Metadata sent with an HTTP request or response. |\n", "| 13 | API key | A credential used to identify or authorize an API client. |\n", "| 14 | JSON | A text data format commonly used for API request and response bodies. |\n", "| 15 | JSON serialization | Converting Python objects to JSON text with `json.dumps()`; `json.loads()` parses JSON text back into Python objects. |\n", "| 16 | Response body | The data returned by a server after a request. |\n", "| 17 | `requests` | A popular Python library for making HTTP requests. |\n", "| 18 | Timeout | A limit on how long a client waits for a response. |\n", "| 19 | Pagination | Splitting a large API response into multiple pages or batches. |\n", "| 20 | Exponential backoff | A retry strategy that increases wait time after repeated transient failures. |\n", "| 21 | Retry | Trying a failed request again, often after a short delay. |\n", "| 22 | Response contract | The expected structure and meaning of data returned by an API. |\n", "| 23 | Environment variable | A named value set outside the program, read in Python with `os.environ.get()`, often used to keep secrets out of source code. |\n", "| 24 | Authorization header | The HTTP header that carries a client's credentials, such as an API token, with each request. |\n", "| 25 | Bearer token | An access token sent as `Authorization: Bearer `, granting access to whoever presents it. |\n", "| 26 | Prepared request | A request that `requests` has fully built, including its final URL and headers, but has not yet sent. |\n", "| 27 | Cursor-based pagination | A pagination scheme in which each response returns a token, such as `next_cursor`, that names the next page to request. |\n", "| 28 | Jitter | A small random amount added to a retry delay so that many clients do not retry at exactly the same time. |\n", "| 29 | `RequestException` | The base class of the `requests` exceptions, so `except requests.RequestException` catches any request failure. |\n" ] }, { "cell_type": "markdown", "id": "1300-slides", "metadata": {}, "source": [ "

Chapter Overview Slides

" ] } ], "metadata": { "language_info": { "name": "python" } }, "nbformat": 4, "nbformat_minor": 5 }