Notes — Module 01: Introduction to APIs¶

These are your personal study notes. Write freely and honestly. Incomplete notes are fine — they show where your understanding still needs work. Return to this file to add insights as they develop over time.

Module: [[modules/01_introduction]] Topic: [[graphql-rest]] Date started: fill in Status: In progress

Concept Map¶

Sketch how the concepts in this module relate to each other. Fill in the Mermaid diagram.

mindmap
  root((APIs))
    HTTP
      Request
        Method
        URL
        Headers
        Body
      Response
        Status Code
        Headers
        Body
    REST
      6 Constraints
        Client-Server
        Statelessness
        Cacheability
        Uniform Interface
        Layered System
        Code-on-Demand
      Resources vs Actions
    GraphQL
      Single Endpoint
      Client-specified queries
      Solves over-fetching
      Solves under-fetching
    Comparison
      When REST wins
      When GraphQL wins

Alternative: draw this on paper, photo it, and link the image here.

Key Insights¶

The "aha moments" — the things that, once understood, made the rest clear. Be specific: "I finally understood X because Y" is more useful than "X makes sense".

1. REST is an architectural style, not a protocol: I finally understood this means there's no REST library to install — it's a set of design constraints you follow (or don't). An API is "RESTful" to the degree it satisfies those constraints.
2. Add insights as you discover them

My Understanding¶

Explain the core concepts in your own words, as if teaching them to someone else. If you can't explain it simply, you don't understand it well enough yet.

What an API Is¶

Your explanation here

What I'm still unsure about: fill in

Fielding's Six REST Constraints¶

Your explanation here

What I'm still unsure about: fill in

Why GraphQL Exists¶

Your explanation here

Connections to Other Topics¶

How does this module connect to things you already know?

Questions That Arose¶

Log questions as they appear. Don't stop to answer them now — just capture them. Then move the serious ones to QUESTIONS.md.

• Write your first question here → added to QUESTIONS.md as Q001
• Write another question

Code Snippets Worth Remembering¶

curl with verbose output¶

# The -v flag shows request headers, response headers, and the status line
# Essential for debugging API calls
curl -v https://jsonplaceholder.typicode.com/posts/1

Why I'm saving this: The verbose flag is the fastest way to see exactly what's going over the wire.

Correct error handling in Python requests¶

import requests

response = requests.get("https://api.example.com/resource/1")

if response.status_code == 200:
    data = response.json()
elif response.status_code == 404:
    # Not found — handle gracefully
    data = None
else:
    # Unexpected error — raise it so it doesn't silently fail
    response.raise_for_status()

Why I'm saving this: The pattern of explicitly handling 200 and 404 separately, then raising for everything else, avoids silently swallowing errors.

What Tripped Me Up¶

Mistakes I made, misconceptions I had, things that confused me more than they should have. Being honest here helps you later.

• REST vs RESTful — I initially thought REST was a specific standard, but it actually works like: the constraints define RESTful architecture, and an API is more or less RESTful depending on how many constraints it satisfies.

Summary in My Own Words¶

Write a 3–5 sentence summary of this entire module without looking at any notes. If you can't do this, you need more study time.

Write here after finishing the module

Last updated: 2026-06-09