APIs and JSON
How apps talk to each other - endpoints, requests, responses and the shape of data.
Before this: Anatomy of a Web App
Objective
Consume a real API through your agent: read endpoint documentation, handle success and failure responses, and parse JSON confidently.
Vocabulary
The words to use when directing your agent.
- API
- Application Programming Interface - a defined way for programs to request services from each other.
- endpoint
- One specific URL an API exposes, like /weather or /users/42.
- REST
- The common web style where URLs name resources and HTTP methods name actions.
- status code
- The number in every response classifying the outcome: 200 ok, 404 missing, 500 broken.
- rate limit
- A cap on how many calls you may make in a time window.
Understand it
Reading a JSON response
JSON nests objects {} and arrays []. Top to bottom: what type is the root, where is the array, what fields does each element carry, which fields hold nested objects. Print the raw JSON once and walk it before writing display code.
Keys, secrets and the frontend
Some APIs require keys proving who is calling. A key in frontend code is public the moment you ship - anyone can read it. Keyless APIs (like Open-Meteo) are perfect for learning; keyed ones belong behind a backend, which you will build in Level 2.
Core concepts
APIs are contracts
Documentation promises: send this, receive that. Your code trusts the contract; the provider may version or change it. Reading docs before coding - and having your agent quote the relevant doc lines - prevents fantasy integrations.
Failure is a first-class case
Networks drop, servers hiccup, limits trip. Code that only handles the happy path is a bug factory. Every API call deserves a designed failure state: retry hint, cached data, or honest error message.
Examples
One endpoint, two futures
GET api.example.com/users/7 returns 200 with a JSON user - or 404 with an error object. Your code branches on status first, then parses. Status-first parsing is the professional habit.
Rate limits in the wild
Free tiers often allow ~60 calls per hour. Polling every second burns through it and returns 429 Too Many Requests. Respect limits or cache aggressively.
Common mistakes
Common mistake
Parsing before checking the status code.
Fix
Branch on status: 2xx parse onward, else handle the failure path explicitly.
Common mistake
Hardcoding API keys into frontend code.
Fix
Prefer keyless APIs while frontend-only; move keyed calls behind a backend in Level 2.
Working with your AI agent
Before any integration, require your agent to produce a three-line integration note: endpoint(s) used, auth requirements, rate limit. If it cannot cite the docs, it has not read them - send it back to read.
Build it
The module’s real project. Your agent builds; you direct and inspect.
Project: Live Data Widget
Extend your Anatomy Lab skills into a purposeful widget: pick any keyless public API and build a focused display of one slice of its data, with designed loading, error and empty states.
Requirements
- Uses a public API requiring NO key (cite it in the README)
- Displays a focused slice of live data (not a raw JSON dump)
- Three designed states: loading, failure with retry affordance, success
- README documents the endpoint(s), their documented limits and the data slice shown
Context for your agent
Help me choose a keyless public API suited to a small widget (suggest three options with trade-offs). After I pick one, build a minimal widget showing one focused data slice with explicit loading, error (with retry) and success states. Quote the API documentation lines for endpoints and rate limits into the README. No frameworks unless I approve.
Verify it - twice
Check every item yourself first. Then hand your agent the prompt and compare verdicts.
Verification prompt - paste into your AI agent
Review my Live Data Widget. Verify PASS or FAIL with evidence: (1) uses only keyless endpoints and the README cites the API docs, (2) HTTP status is checked before parsing, (3) loading, failure-with-retry and success states are all implemented and reachable, (4) displayed values correspond to the real API response schema, (5) no secrets in code or git history. Then hit the endpoint yourself and tell me whether my code would survive: a 10-second delay, a 500 response, and a schema change moving the data one level deeper.
Run this against “APIs and JSON” after your own checklist pass. Where the agent and you disagree, investigate before moving on.
Review questions
Answer out loud. If you cannot, revisit before moving on.
What does your widget do differently when the status is 500 versus 404?
Why is a frontend API key effectively public?
Walk through your JSON's shape: root type, array location, element fields.
You can now
- Integrate real APIs by reading contracts, not guessing
- Design all response states, not just success
- Keep keys out of frontend code by choosing the right architecture
Up next
Databases and CRUD