REST APIs — POST, Headers & Auth

• Send JSON to a server with requests.post(url, json=...).
• Read created resources (status 201) and form responses.
• Authenticate with the four common patterns: query, header, Bearer token, Basic auth.
• Keep secrets out of source — environment variables and .env files.

GET       read       ?q=python              safe to repeat
POST      create     body: {"title": ...}   creates a new thing
PUT       replace    body: {"title": ...}   overwrite by id
PATCH     update     body: {"title": ...}   partial change
DELETE    remove     ?id=42                 remove by id

The five HTTP verbs. Today is POST. The others come up in Level 4's SQLite + Flask lessons.

Your first POST

The test API https://httpbin.org/post echoes back what you sent — perfect for learning.

import requests

r = requests.post(
    "https://httpbin.org/post",
    json={"name": "Aisyah", "score": 92},
    timeout=5,
)
print(r.status_code)            # → 200 (httpbin always echoes 200)
print(r.json()["json"])         # → {'name': 'Aisyah', 'score': 92}

The json= kwarg serialises your dict to JSON and sets the right Content-Type header automatically.

Form data vs JSON

# Form data (looks like HTML form submission)
r = requests.post("https://httpbin.org/post", data={"k": "v"})

# JSON (most modern APIs)
r = requests.post("https://httpbin.org/post", json={"k": "v"})

Four common auth patterns

1. Query parameter

r = requests.get(
    "https://api.openweathermap.org/data/2.5/weather",
    params={"q": "Kuala Lumpur", "appid": API_KEY},
    timeout=5,
)

2. Header (custom)

r = requests.get(
    "https://api.example.com/data",
    headers={"X-API-Key": API_KEY},
    timeout=5,
)

3. Bearer token (most modern APIs, including OpenAI & Anthropic)

r = requests.get(
    "https://api.example.com/data",
    headers={"Authorization": f"Bearer {TOKEN}"},
    timeout=5,
)

4. Basic auth (username + password)

r = requests.get(
    "https://api.example.com/data",
    auth=("username", "password"),
    timeout=5,
)

Where to keep your key

NEVER commit a key to git. Use an environment variable or a local .env file that's git-ignored:

import os
API_KEY = os.environ["OPENWEATHER_KEY"]

# Or, in a .env file:
# OPENWEATHER_KEY=abcd1234

# Then in code:
from dotenv import load_dotenv
load_dotenv()
API_KEY = os.environ["OPENWEATHER_KEY"]

python-dotenv (pip install python-dotenv) reads .env into os.environ. Add .env to .gitignore — and never paste a real key into a screenshot, a chat or a blog post.

JSONPlaceholder accepts POSTs without auth — it pretends to save your data and returns a 201 with a fake id. Perfect playground.

# new_todo.py — create a new todo via POST
import requests

URL = "https://jsonplaceholder.typicode.com/todos"

new = {
    "userId": 1,
    "title":  "Finish PY-L4-11 homework",
    "completed": False,
}

r = requests.post(URL, json=new, timeout=5)
r.raise_for_status()

print("status:", r.status_code)
print("body  :", r.json())
print(f"\n🎉 server assigned id = {r.json()['id']}")

Sample output

status: 201
body  : {'userId': 1, 'title': 'Finish PY-L4-11 homework', 'completed': False, 'id': 201}

🎉 server assigned id = 201

The status is 201 Created, not 200. The response body is your todo plus a server-assigned id. (JSONPlaceholder doesn't really save it — but a real API would.)

Read the diff

The full POST recipe: build a Python dict, pass it via json=, check status, read the returned object — especially any server-generated fields like id. From here on every API write operation looks the same.

POST sends data; json= makes it easy. Auth comes in four flavours — query, header, Bearer, Basic — and you pick whichever the API requires. Never paste a key into source: use os.environ + a .env file. Tomorrow we cash in: trivia questions live from a real API.