APIs — Software's Universal Language
An API (Application Program Interface) is a contract between two pieces of software — one exposes capabilities, the other consumes them. You don't need to know how an API works internally, only its inputs and outputs. In this chapter we cover three levels: local library APIs (like Pandas), internet REST APIs, and a real-world NBA data example.
18.1 What Is an API?
Think of an API like a restaurant menu. The kitchen (service) is complex — but the menu (API) tells you exactly what you can order (inputs) and what you'll get back (outputs). You never need to walk into the kitchen.
import pandas as pd
# Create a dictionary — your "order"
data = {
"Artist": ["MJ", "AC/DC", "Pink Floyd"],
"Album": ["Thriller", "Back in Black", "Dark Side"],
"Year": [1982, 1980, 1973]
}
# Pass it to the Pandas API
df = pd.DataFrame(data) # ← API call
# Use the API — you don't know how it
# renders a table, you just call .head()
print(df.head())
print(df.mean(numeric_only=True))The Black-Box Principle: When you write pd.DataFrame(data), you're making an API call. Pandas is implemented partly in C and Cython — you don't need to know that. You provide data in, get a DataFrame out. The same is true for .head(), .mean(), and every other method.
Click each step to animate the data flow through the Pandas API. Watch how your code (the client) never touches the internals.
Click each step to see how your Python code translates into API calls and what each one returns.
18.2 REST APIs — Talking Over the Internet
REST stands for Representational State Transfer. A REST API lets your program communicate with a web service over the internet using standard HTTP messages. Your code becomes the client, the web service is the resource, and the location of the service is the endpoint.
Select an HTTP method, then click Send Request to animate the full client → endpoint → server → response flow.
REST APIs usually send and receive JSON (JavaScript Object Notation). It maps directly to Python dictionaries and lists. Click a field to highlight its role.
import requests
# 1. Send a GET request to a REST endpoint
url = "https://api.example.com/teams/1610612744"
response = requests.get(url)
# 2. Check the status code
print("Status:", response.status_code) # 200
# 3. Parse the JSON response into a Python dict
data = response.json()
# 4. Access fields just like a dictionary
print("Team:", data["team"]["name"])
print("Wins:", data["team"]["wins"])
# 5. Loop through a list response
teams = requests.get("https://api.example.com/teams").json()
for team in teams["results"]:
print(team["name"], "-", team["city"])requests library handles TCP connections, headers, and encoding automatically.
200 = success; 404 = not found; 401 = unauthorized.
18.3 Real World: NBA API Case Study
Sports data changes constantly — new games, new stats, new standings. This makes it a perfect real-world API use case. The NBA API (by Swar Patel) wraps NBA.com endpoints so you can pull any team's game log, stats, and standings with a single Python call.
from nba_api.stats.static import teams
from nba_api.stats.endpoints import leaguegamefinder
import pandas as pd
# Step 1 — Get all teams as a list of dicts
nba_teams = teams.get_teams()
# Step 2 — Convert to DataFrame for easy lookup
teams_df = pd.DataFrame(nba_teams)
# Step 3 — Find the Warriors' unique ID
warriors_row = teams_df[teams_df["nickname"] == "Warriors"]
warriors_id = warriors_row["id"].values[0]
print("Warriors ID:", warriors_id)
# Step 4 — Make the API call
gamefinder = leaguegamefinder.LeagueGameFinder(
team_id_nullable=warriors_id
)
games_df = gamefinder.get_data_frames()[0]
print(games_df[["GAME_DATE","MATCHUP","PLUS_MINUS"]].head())What's happening under the hood? When you call LeagueGameFinder(), the nba_api library builds an HTTP GET request, sends it to an NBA.com endpoint, receives a JSON payload, and converts it to a DataFrame — all automatically.
GSW vs. TOR = home game | GSW @ TOR = away game. The vs. / @ symbols encode home/away.
This simulates the Warriors' game log from the NBA API. Filter by game type and see the PLUS_MINUS chart update in real time.
| GAME_DATE | MATCHUP | WL | PTS | OPP_PTS | PLUS_MINUS |
|---|
Click Trace Request to step through every layer — from your Python line, through the nba_api library, to NBA.com servers, and back as a DataFrame.