Skip to content
build-3000
backend

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.

Self-verified0/8
Functional
Architecture
Security
Testing

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.

  1. What does your widget do differently when the status is 500 versus 404?

  2. Why is a frontend API key effectively public?

  3. 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