How Apps Talk: APIs Revealed

Before You Study (5 mins)

Lesson focus: Lesson 08 made you fluent in reading JSON files locally. Today you read JSON files that live on other people's computers — anywhere in the world — by making your first API calls. When you tap "refresh" in any app, what happens under the hood is: your client opens an HTTP request, a server somewhere receives it, runs some logic, and sends back a JSON response. That cycle is what you're going to perform yourself today, deliberately, with curl first and then fetch() from your game.

What you should have ready:

• Terminal fluency from Lesson 04 — we'll use curl extensively
• Browser DevTools open (F12 or Cmd+Option+I) — Network tab visible
• Your Snake game project — we'll add an API call to it
• Internet connection — APIs require it
• About 60 minutes

The Concept

An API (Application Programming Interface) is a contract. The contract specifies: which URLs you can request, what HTTP method to use (GET, POST, ...), what headers to send, what shape the request body should have, and what shape the response will come back in. Your code holds up its side of the contract by sending well-formed requests; the server holds up its side by sending well-formed responses. When both sides honor the contract, two systems built by different people in different languages talk seamlessly.

The request–response cycle has a fixed shape:

       ┌────────────────┐         GET /weather?city=Mumbai           ┌──────────┐
       │   Your client  │────────────────────────────────────────────▶│  Server  │
       │  (browser/app) │                                              │  (API)   │
       │                │◀─── 200 OK + JSON body ────────────────────│          │
       └────────────────┘                                              └──────────┘

A request has four parts:

• Endpoint (the URL): https://api.example.com/v1/weather?city=Mumbai
• HTTP method (the verb): GET, POST, PUT, PATCH, DELETE
• Headers (metadata): Content-Type: application/json, Authorization: Bearer <token>, User-Agent: ...
• Body (payload, only on POST/PUT/PATCH): a JSON document with the data you're sending

A response has three parts:

• Status code (the verdict): a 3-digit number telling you the outcome
• Headers (metadata about the response)
• Body (the data, almost always JSON)

The five HTTP verbs each map to an intent:

"Idempotent" means: doing the same operation multiple times produces the same end state. Calling GET /users/42 ten times returns the same user. Calling DELETE /users/42 ten times leaves the user equally deleted (the second call returns 404, but the system state is the same). POST /orders is not idempotent — calling it ten times creates ten orders, which is why retried requests need idempotency keys in production systems.

Status codes are a protocol with five families. A senior engineer can debug most issues from the status code alone:

The instinct that separates beginners from senior engineers: when a request fails, the status code tells you immediately whether the bug is on your side (4xx) or the server's side (5xx). Don't blame their server when it returned 400.

Want the full architectural story — REST vs GraphQL vs gRPC, idempotency keys, authentication patterns, OpenAPI specs, the API economy? The companion article What is an API and How Do APIs Actually Work is calibrated to extend this lesson. Read it after today's hands-on practice to lock in the architectural model.

Quick Concepts

What We Will Build

By the end of this lesson, you will have done these specific things:

1. Made your first curl call to a public API in your terminal:
   bash

   Copy

   curl https://api.quotable.io/random
   

   Read the JSON that comes back. Recognized the structure: content, author, tags.
2. Inspected the headers and status by adding the -i flag:
   bash

   Copy

   curl -i https://api.quotable.io/random
   

   Identified the status code (200), Content-Type: application/json, and Cloudflare's Server header.
3. Made a different request to test status codes — call a non-existent endpoint and watch a 404 come back:
   bash

   Copy

   curl -i https://api.quotable.io/this-does-not-exist
   

4. Wrote your first browser-side API call in your Snake game using fetch():
   javascript

   Copy

   async function loadQuoteOfTheDay() {
     const response = await fetch('https://api.quotable.io/random')
     if (!response.ok) {
       console.error('API failed:', response.status)
       return null
     }
     const data = await response.json()
     return data
   }
   

5. Added a "Quote of the Day" to your loading screen by calling loadQuoteOfTheDay() and showing data.content and data.author to the player.
6. Watched the request in DevTools' Network tab — found your call, expanded it, looked at Request Headers / Response Headers / Response body. The Network tab will be your debug surface for every API call you'll ever make.
7. Triggered a 4xx and a 5xx on purpose to feel them: try a malformed request to a real API; turn off your wifi mid-call and observe the network failure.
8. Added the await and try/catch around your fetch so the game doesn't crash if the API is down — defensive programming for a world that occasionally fails.

The shift from curl (terminal) to fetch (browser) is intentional. Both make the same HTTP request under the hood; switching between the two as you debug will become second nature in Module C.

Think About

Before studying, consider:

1. The "weather app" on your phone has no idea what the weather is. It knows how to ask a weather API. The actual atmospheric measurement is happening at sensor stations around the world, processed by NOAA / IMD / WMO, surfaced through APIs, and your phone is just the last mile. How many systems do you think a single weather check passes through?
2. If POST /orders creates an order and your network is flaky and you retry the request, you might create two orders for one click. How would you design the API to make this safe? (Hint: this is exactly what idempotency keys solve in production.)

By the End

After this lesson, you'll:

• ✅ Have made your first curl API call from the terminal
• ✅ Know the 4 parts of a request and 3 parts of a response
• ✅ Recognize the 5 HTTP verbs and their intents
• ✅ Know what each status code family means (2xx success, 4xx your fault, 5xx their fault)
• ✅ Have called a real API from your Snake game using fetch()
• ✅ Have watched the call land in DevTools' Network tab
• ✅ Have wrapped the call in try/catch so a failed API doesn't crash your game

The internet is a conversation. Today you join it. 🛎️

What We Learned

• An API is a contract. It declares what URLs exist, what verb to use, what headers to send, what body to expect. Both sides honor the contract; the systems integrate cleanly.
• The request–response cycle has a fixed shape. A request is method + URL + headers + body. A response is status + headers + body. Every API call you ever make fits this pattern.
• The five HTTP verbs each carry intent. GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes. Pick the wrong verb and your API stops being predictable.
• Status codes are a protocol. 2xx success, 3xx redirection, 4xx client error (your fault), 5xx server error (their fault). The status code alone tells you which side to debug.
• Idempotency separates safe verbs from dangerous ones. GET / PUT / DELETE are idempotent by spec; POST is not. Real production systems use idempotency keys to make POST retry-safe.
• fetch() (browser) and curl (terminal) make the same HTTP request under the hood. The ability to switch between them while debugging is what makes API work feel comfortable instead of mysterious.

Commands We Used

# A simple GET — fetch a random quote
curl https://api.quotable.io/random

# Include headers + status in the output (great for debugging)
curl -i https://api.quotable.io/random

# Pretty-print the JSON response (requires jq: brew install jq)
curl -s https://api.quotable.io/random | jq .

# Just the status code
curl -o /dev/null -w "%{http_code}\n" -s https://api.quotable.io/random
# → 200

# Trigger a 404
curl -i https://api.quotable.io/this-does-not-exist

# A POST request with a JSON body (echoes the body back)
curl -X POST https://httpbin.org/post \
  -H "Content-Type: application/json" \
  -d '{"hello": "world"}'

# A request with an Authorization header (typical for authenticated APIs)
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/private

The browser equivalent — fetch() — used in your game:

// GET — read data
async function loadQuoteOfTheDay() {
  try {
    const response = await fetch('https://api.quotable.io/random')

    if (!response.ok) {
      console.error('API returned non-2xx:', response.status)
      return null
    }

    const data = await response.json()
    return { content: data.content, author: data.author }
  } catch (err) {
    // Network failure (offline, DNS error, server unreachable)
    console.error('Fetch threw:', err)
    return null
  }
}

// Use it in the game's loading screen
const quote = await loadQuoteOfTheDay()
if (quote) {
  document.getElementById('quote').textContent = `"${quote.content}" — ${quote.author}`
} else {
  document.getElementById('quote').textContent = 'Welcome to Snake.'
}

// POST — send data
async function submitScore(score) {
  const response = await fetch('https://your-api.example.com/scores', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ playerName: 'Divyanshu', score })
  })
  return response.ok
}

The status-code cheatsheet to keep nearby:

Why It Matters

Almost every interesting product on the internet today is a thin shell around an API call (or twenty). Stripe is "the payments API." Twilio is "the SMS API." OpenAI is "the LLM API." Mapbox is "the maps API." When you ship a product in 2026, you assemble it from APIs the way an electronics engineer assembles a circuit from chips: each chip does one thing well, you wire them together, and the system you built is the differentiator.

This means API fluency compounds across your entire career. Every job, every product, every side project will involve calling APIs you didn't build. The skill is not memorizing endpoints — it's reading API docs efficiently, understanding the request-response cycle, recognizing status codes by family, and writing defensive code that handles failures gracefully.

The deeper insight is observability. Senior engineers don't guess when an API call fails. They look at:

• The status code (which side's bug?)
• The response body (what did the server actually say?)
• The request headers (did I send what I thought I sent?)
• The DevTools Network tab (did the request even leave?)

This habit — check the protocol layer first, before suspecting the application — is what makes senior engineers feel slow on Day 1 and fast on Year 5.

What this lesson glossed over but you'll meet in Module C and beyond:

• Authentication patterns: API keys, OAuth 2.0, JWT tokens. Lesson 13 builds your first authenticated API.
• Rate limiting: most APIs throttle you to a fixed number of calls per minute. The 429 status code is what you'll see when you hit it.
• Pagination: when an API would return 100,000 results, it doesn't — it returns 50 with a cursor. You learn the cursor protocol.
• Idempotency keys: how production systems make POST safely retryable.
• REST vs GraphQL vs gRPC: three architectural styles, each with trade-offs. Most APIs you'll meet are REST.
• OpenAPI specifications: machine-readable API contracts that auto-generate client SDKs and interactive docs.

The companion article What is an API and How Do APIs Actually Work walks through the architectural styles, idempotency in depth, and the API economy. Read it this week to extend the model in your head.

Checklist

• I made my first curl API call and saw JSON come back
• I added -i to see headers and status code
• I triggered a 404 on purpose by calling a non-existent endpoint
• I added a fetch() call to my Snake game's loading screen
• I wrapped the call in try/catch and if (!response.ok) so a failed API doesn't crash the game
• I watched the request land in DevTools' Network tab
• I can name the 5 HTTP verbs and what each one means
• I can explain "idempotent" in my own words

Quick Quiz

Q1: What does the verb GET do?

• A) Send data to create a resource
• B) Read a resource — retrieve data ✓
• C) Delete a resource

Q2: A response with status 404 means what?

• A) The server is broken
• B) The endpoint or resource doesn't exist on the server ✓
• C) Your internet is down

Q3: Why is POST not idempotent?

• A) POST can be slow
• B) Calling it multiple times creates multiple resources, so each call has different effects ✓
• C) POST always fails on the second call

Q4: What format do most modern APIs use for the response body?

• A) PDF
• B) XML
• C) JSON ✓

Q5: A 5xx status code tells you whose fault the failure is?

• A) Yours (the client)
• B) The server's ✓
• C) The internet provider's

Bonus Challenge

Find a free public weather API (Open-Meteo is free with no key required). Add a "current weather" feature to your game's loading screen. The temperature in your city should appear before the game starts. If the API fails (no internet, server down), the game should still load — gracefully, with a default "Snake says hi" message. Two outcomes:

1. You experience how easy it is to plug a real-world data source into a personal project.
2. You experience the discipline of handling failure — the difference between code that "works on my machine" and code that survives the messy real internet.

Next Lesson

Lesson 10: MILESTONE — Your App Is Online

You'll learn: Module B is complete the moment your containerized, tunneled, JSON-configured, API-calling Snake game is reachable from any phone in the world. Tomorrow we verify that — and submit the milestone deliverable that closes Module B.

The internet talks back. You're listening now. 🛎️