APIs feel like magic once they click.

What is an API?

API stands for Application Programming Interface. That sounds abstract, but the idea is simple: an API is a controlled doorway into another system.

Why APIs feel magical

APIs are powerful because they let small programs do big things. I do not need to own the weather station, movie database, or AI model. I just need to know how to ask the API correctly.

API vocabulary that matters

Most API confusion comes from vocabulary. These are the terms I need first.

My basic API workflow

The workflow is the same whether I am using Weather.gov, TMDB, OpenAI, GitHub, Cloudflare, or another service.

Start with curl

curl is one of the best ways to learn APIs because it shows the request and response without hiding the details behind a library.

# Basic GET request
curl https://api.example.com/data

# Show response headers too
curl -i https://api.example.com/data

# Send a header
curl -H "Accept: application/json" https://api.example.com/data

# Pretty-print JSON with jq
curl https://api.example.com/data | jq

JSON is the language of many APIs

JSON looks like JavaScript object syntax, but it is used by many languages. Python reads it like dictionaries and lists.

{
  "title": "The Matrix",
  "year": 1999,
  "genres": ["Action", "Sci-Fi"],
  "rating": 8.7
}

movie["title"]
movie["year"]
movie["genres"][0]
movie["rating"]

Three APIs that make the idea click

These are good examples because each one teaches a different API lesson.

Example 1: Weather.gov

Weather.gov is a good API for learning because it returns real forecast data. The usual pattern is: ask for grid metadata using latitude and longitude, then follow the forecast URL returned by the API.

# Step 1: get forecast metadata for a latitude/longitude
curl -H "User-Agent: LaunchShellAPIPractice (you@example.com)" \
  "https://api.weather.gov/points/40.7128,-74.0060" | jq

# Step 2: use the forecast URL returned in the JSON
curl -H "User-Agent: LaunchShellAPIPractice (you@example.com)" \
  "https://api.weather.gov/gridpoints/OKX/33,37/forecast" | jq

Weather.gov with Python

Once the curl request works, Python can make the same request and extract fields from the JSON response.

import requests

headers = {
    "User-Agent": "LaunchShellAPIPractice (you@example.com)"
}

points_url = "https://api.weather.gov/points/40.7128,-74.0060"

points = requests.get(points_url, headers=headers, timeout=10)
points.raise_for_status()

data = points.json()
forecast_url = data["properties"]["forecast"]

forecast = requests.get(forecast_url, headers=headers, timeout=10)
forecast.raise_for_status()

periods = forecast.json()["properties"]["periods"]

for period in periods[:3]:
    print(period["name"])
    print(period["temperature"], period["temperatureUnit"])
    print(period["shortForecast"])
    print()

Example 2: TMDB API

TMDB is useful for movie projects because it can turn a simple title search into structured movie data: titles, release dates, summaries, ratings, poster paths, genres, and related IDs.

# Store the token in an environment variable, not directly in code
export TMDB_BEARER_TOKEN="paste_token_here"

# Search for a movie
curl --request GET \
  --url "https://api.themoviedb.org/3/search/movie?query=The%20Matrix&include_adult=false&language=en-US&page=1" \
  --header "Authorization: Bearer $TMDB_BEARER_TOKEN" \
  --header "accept: application/json" | jq

TMDB with Python

This connects directly to a movie database project. Instead of manually typing every movie field, a script could search TMDB and fill in basic metadata.

import os
import requests

token = os.environ["TMDB_BEARER_TOKEN"]

headers = {
    "Authorization": f"Bearer {token}",
    "accept": "application/json"
}

params = {
    "query": "The Matrix",
    "include_adult": "false",
    "language": "en-US",
    "page": 1
}

response = requests.get(
    "https://api.themoviedb.org/3/search/movie",
    headers=headers,
    params=params,
    timeout=10
)

response.raise_for_status()

results = response.json()["results"]

for movie in results[:5]:
    print(movie["title"], movie.get("release_date", "unknown"))
    print(movie.get("overview", "")[:160])
    print()

Example 3: OpenAI API

The OpenAI API is different from a normal data API. Instead of only returning stored facts, it can generate or transform text based on input. That makes it useful for drafting, sorting, classifying, summarizing, building study tools, and creating helper features inside apps.

# Store the key outside the code
export OPENAI_API_KEY="paste_key_here"

# Example request
curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "input": "Explain APIs in one paragraph for a beginner."
  }'

OpenAI API with Python

In Python, the basic pattern is: load the API key from the environment, create a client, send input, and print the model output.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.5",
    input="Give me three beginner project ideas for learning APIs."
)

print(response.output_text)

API keys and environment variables

API keys are like passwords for services. They should not be pasted into public code, static HTML, screenshots, GitHub repos, or browser JavaScript.

export OPENAI_API_KEY="secret"
export TMDB_BEARER_TOKEN="secret"

python3 app.py

# Bad idea
api_key = "paste-real-key-here"

GET vs POST

Most beginner API work starts with GET and POST.

Status codes I should recognize

Status codes are the API's first explanation of what happened.

Beginner mistakes to avoid

Most beginner API problems are predictable.

Good beginner API projects

These are practical projects that would fit LaunchShell well.

How this connects to LaunchShell

APIs fit perfectly with the LaunchShell style because they turn small projects into real systems.

API cheat sheet

This is the short version I would keep nearby.

# Basic request
curl https://api.example.com/data

# Include headers
curl -H "Accept: application/json" https://api.example.com/data

# Include an API bearer token
curl -H "Authorization: Bearer $API_TOKEN" https://api.example.com/data

# Pretty-print JSON
curl https://api.example.com/data | jq

# Python requests pattern
import requests

response = requests.get(url, headers=headers, params=params, timeout=10)
response.raise_for_status()
data = response.json()

# Environment variables
export API_TOKEN="secret"

# Git safety
echo ".env" >> .gitignore

Final idea