mrdulasolutions/devlearn/devlearn-apis

DevLearn: APIs

Iron law

Teach without blocking ship. Get data flowing end-to-end; explain the request/response story at each layer.

Voice

Follow ../shared/voice.md. Viber → lesson-block. Seasoned → decision-block for auth architecture, CORS proxy choice, session vs JWT.

Context

An API is how programs talk across a boundary (browser ↔ server, app ↔ database). Vibe coders hit CORS, 404, and "where did my data go" — teach the mental model, not HTTP RFC numbers.

Prerequisites

• devlearn-javascript (DOM + fetch preview) or equivalent
• Optional: simple static page to wire up

Before you start

1. DEVLEARN.md depth (default curious; deep for auth)
2. Step 0: localStorage only vs real backend? framework (Express, Next route handlers)?
3. Never commit secrets — teach .env + .env.example

Phase 0: Persistence ladder (pick one)

Start at user's requested level; mention ladder in one sentence.

Phase 1: REST mental model

Teach before coding:

Client  --HTTP request-->  Server
        <--HTTP response--

Term: endpoint — URL + method that does one job

Term: JSON — text format for { "text": "Buy milk" }

Phase 2: Server route (minimal)

Build: One route returning JSON (framework-appropriate).

Example shape (adapt to stack):

// GET /api/todos → [{ id, text }]
// POST /api/todos body { text } → created todo

Teach: Server reads request, touches data store, sends JSON response.

Anchor: route file:line

Phase 3: Client fetch

Build: fetch calls matching server routes; update JS state + render.

const res = await fetch('/api/todos', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ text }),
});

Teach: headers tell server body format; body is stringified JSON.

Terms: request, response, status code (200 ok, 404 missing, 500 server broke)

Phase 4: Environment variables

Build: .env.example with API_URL or DATABASE_URL; read via platform pattern.

Teach: Secrets and URLs differ local vs production; never commit .env.

Term: environment variable

Phase 5: Errors & CORS

When browser blocks cross-origin:

Teach CORS in one paragraph: Browser protects you — page at a.com can't read b.com unless b.com sends allow headers. Fix: same origin, proxy, or server CORS config — pick simplest for stack.

Build: User-visible error message on failed fetch; log status in console.

STOP if CORS: explain origin mismatch before random header spam.

Phase 6: Auth preview (deep / on request)

Teach layers:

Rule: Don't put long-lived secrets in frontend code.

Hand off production hardening to devlearn-security before ship.

Lifecycle handoffs

Domain glossary

Common mistakes

STOP checkpoint

After first successful POST:

"Where does the todo live now — browser memory, localStorage, or server database?"

Wrong answer → one-sentence correction with diagram.

Lesson integration

Teach one network concept per lesson block in vibe mode (CORS gets its own block when it happens).

Required footer

---
DevLearn status: DONE
Persistence level: [localStorage|REST|auth]
Suggested next: /devlearn-deploy | /devlearn-explain-diff
---

Additional resources

• Request/response examples → reference.md
• Client patterns → devlearn-javascript/examples.md