🔪 Server (The Kitchen)
The actual machine running the code. It stores your data and does the work — but you can't talk to it directly.
📒 API (The Menu)
A set of rules and endpoints that define what you’re allowed to ask the kitchen to do.
🧾 Endpoints (Like a ticket printer at a kitchen station)
Think of these as the addresses for different kitchen stations — the grill, the fryers, the sauce line, the dish pit — where your requests get sent and processed.
📏 Rules (How you ask the kitchen staff for what you need)
You can’t just yell into the kitchen. The API expects very specific behavior:
What methods to use
GET– read somethingPOST– create somethingPATCH– update somethingDELETE– remove something
What data format is expected
(You can’t just use any method at any endpoint.)
Usually JSON.
Your request must be structured just right — like using the correct key names, data types, and nesting.
What authentication is required
Many endpoints require an API token, sent in a header like Authorization: Bearer YOUR_TOKEN.
Rate limits
Only a certain number of requests per minute/hour — otherwise the kitchen throws you out.
Error handling
You’ll get error codes like 403 Forbidden, 404 Not Found, or 429 Too Many Requests if something goes wrong.
🤵 SDK (The Waiter)
A friendly helper (i.e., a software development kit) who knows how to speak to both you (as a dev) and the kitchen (the server).
Instead of shouting raw HTTP requests, you just ask nicely in Python and let the SDK translate it.
🪪 Authentication Token (The Membership Card)
“I’m allowed to be here — and here’s what I’m allowed to order.”
Your token proves your identity and permissions. Without it, you’re not getting served.
💡 You need an auth token to access private endpoints, and to authenticate yourself for some public ones too.
🔒 Private APIs / Endpoints
🧝♀️ A VIP club at the top of a skyscraper — no token, no entry.
Example: Accessing your Notion workspace data.
🌐 Public APIs / Endpoints
🌃 A regular restaurant — some info is available to anyone, but the best stuff still requires a reservation.
Example: GitHub’s public API lets you view user profiles, but limits how often and what you can do without authenticating.
Maybe you only have access to the salad bar. Or maybe you’re platinum and can order off the secret menu.
🤵♀️ Client (Your Waiter)
Your personal instance of the SDK — the one assigned to your table.
You give them your auth token (membership card), and they handle every order for you.
🎭 Here’s how the interaction starts:
Step 1: You introduce yourself
waiter = Client(auth=notion_token)
🗣️ You say:
“Hi, I’ve got a reservation. Here’s my membership card. I’ll be ordering shortly.”
The waiter nods, tucks your card in their pocket, and prepares to serve.
Step 2: You place your order
waiter.pages.retrieve(page_id="...")
🗣️ Now you say:
“One Notion page, please — page ID 12345. Light on the 404s.”
The waiter formats the request, sends it to the right kitchen station (endpoint), and returns exactly what you asked for.
