On this page

Notes · Block 1 · Week 2 · Building APIs and the backend

APIs: Rip Off the Cushion

From an echo chat with no process to a raw POST request that plans Aarav's week.

Block 1 · Ship the first systemSelf-paced

The one thing to keep

An LLM is not magic inside your app. It is a machine at an address, and you reach it like any API: an address, an action, a key and a package. The process is your prompt plus your user's input, sent to that address. None of it counts until your verifier says the output helps the person you built it for.

Aarav is your first customer. The FDE job is to take what you found by hand in his week and put a working system around it that he can actually use.

Read once end to end, then rebuild section 10 and section 13 on your own machine.

01Where We Left Off: A Chat That Repeats You

The Gradio app from The first interface: building UI: message is the input, the return line is the output, and there is nothing in between.

What you have to find is the process: the step that turns your user's input into an output they can use. You cannot write the process for a problem you have not done by hand.

02The Verifier Most People Skipped

A spec has three parts: the person, the golden dataset (ideal input and ideal output, written after talking to real users) and the verifier, a written condition that tells you whether an output is good. If you cannot tell a good output from a bad one in your user's domain, do not build yet.

Adding two numbers, an exam result and a refund decision gave three families: verification by rule, by judgment, and unverifiable. A system that gives the same output for the same input every time is deterministic, and this block lives there.

03Why Learn It When Agents Can Write It

Thinking can be outsourced. Understanding cannot.

We are not learning code to write it faster by hand. We are learning how deterministic systems behave, because a system you do not understand is a system you cannot verify: an agent, a mobile app or legacy enterprise software.

04Filling the Process With One Line

With the manual work for Aarav done, the process fits in one line of pseudocode:

The prompt is the valuable part: the instruction refined after talking to real Aaravs. Your task is to make that line real with a Groq key (console.groq.com/keys) and GPT OSS 120B, free at 30 requests per minute.

05Four Minutes, and What the Machine Said

A worked example: four learners each had four minutes to fill that one line. Read their attempts as the mistakes you are likely to make yourself.

Attempt A	An OpenAI client pointed at the Groq address. Errors: missing API key, then `gr` not defined. Every error is a hint about what broke.
Attempt B	`LLM` was never defined, so the call could not run.
Attempt C	It ran: the only working answer of the first three. It also carried things nobody asked for and no prompt at all.
Attempt D	Cleanest: template kept, process filled. But the interface was swapped, names changed for no reason, and the prompt was the docs' default.

06Working Is Not the Same as Useful

Attempt C's code passed; the plan did not. It was full of code, and Aarav is a business analyst who cannot read Python yet. If the most complex technology on Earth does not deliver value to the end user, it was a waste of everyone's time.

07The Minimum Path

Under time pressure with one clear instruction, nobody changes the interface or adds ten parameters. Extra, unrequested structure is the fingerprint of pasting the task into an AI without understanding. Ask first: what is the smallest change that makes this work?

08Go to the Source, and Read the 404

Go to the official source before any AI. Groq's quickstart (pip install groq, export GROQ_API_KEY, a short script) failed as pasted:

Error 404

The model llama-3.3-70b-versatile does not exist or you do not have access to it.

404 is the client's mistake and means not found. Not found what? The message says: the model. Change the name to GPT OSS and run again. The status code tells you whose fault it is; the message tells you what.

09Free Is a Design Decision

Groq's free tier: 30 requests per minute, roughly 200,000 tokens and 1,000 requests a day. With a per-user quota, that powers a real MVP for one or two users at zero cost.

10Where Is the URL? Four Principles in the Code

Test it in httpie.io/app (a browser address bar only sends GET). api.groq.com on its own failed: DNS finds a server, it does not tell the server what you want. The API reference gives the full endpoint:

POST https://api.groq.com/openai/v1/chat/completions

The whole Groq API, tested without writing code. You can do this in the browser right now.

11Prompt + Input = Package

The message content became a plain instruction followed by Aarav's real workflow:

"Here is the workflow of an analyst working at an IT company in India. Diagnose and generate a plan to automate this work, or a part of the work." [Aarav's workflow pasted below]

Both share one content field, but the instruction is yours and stays the same; the workflow is his and changes every time. The loop: chat UI captures input, prompt plus input goes to the LLM API, JSON comes back, you extract content, Gradio renders it to Aarav. Judge it against the golden pair, not "looks good".

12The Cushion: What a Library Hides

In the SDK code that worked, neither the URL nor POST is visible: both are hidden behind abstraction.

A passenger enjoys the comfort of a car. A driver understands its controls and knows what to do when things go wrong.

Comfort without understanding comes at the cost of control.

In software, SDKs, libraries, no-code/vibe-coding tools are like comfortable passenger seats. They make the journey easier by hiding the machinery underneath.

But hidden machinery doesn't disappear.

When something breaks, what you understand determines what you can fix.

To drive software machines, understand its controls: APIs, endpoints, authentication, requests, and responses.

Use abstractions for comfort. Build understanding for control.

13Ripping Off the Cushion: requests.post

Same as the browser test, now in Python, with every principle visible:

The key comes from your environment. Set it with export GROQ_API_KEY=... in the terminal; it vanishes on restart.
The content is static prompt plus dynamic message. That one line in front of Aarav's text is the P in input, process, output.
If import requests fails, run pip install requests.

14Reading the Plan as Aarav Would

The plan used Aarav's real week: open Jira, read the tickets, write the status, post on Slack. Useful. Then it drifted into architecture, databases and languages: jargon. The verifier produced a prompt change: no jargon, one step at a time, the minimum action needed now. One JQL line on day one, Python on day two, the Jira API by week four.

15Any Machine, Four Lines

The raw version is provider-agnostic: swap the URL and key for OpenAI's and the same code runs. No new package, no dependence on anyone's SDK.

The four questions for any machine

What is the address? What is the action? Do I need a key, and how do I get it? What package does it expect? Answer those and about four lines connect your app to any machine on the internet.

Practice targets: the public-apis list.

16From the Q&A

Make my API run a shell script?	Bash and Python speak different languages. You need a common language and rules: an interface problem, the one this block keeps solving. Send your script for a specific answer.
The key showed in the network inspector	Covered when you build your own API. Security comes in levels, chosen by what is at stake: a to-do app and a Fortune 500 company do not need the same lock.
Host my own API locally?	Covered when you build your own API, the next step after this lesson.
Feedback	Your best feedback comes from your own Aarav: put the output in front of the person you built it for.

17Words You Met

ProcessThe step that turns input into output: your prompt plus the user's message, sent to an LLM.

Golden datasetIdeal input and output pairs, written from doing the job by hand.

VerifierA written condition that says whether an output is good enough for the user.

Deterministic systemSame input, same output, every time. Verifiable by rule.

EndpointThe full address of one resource, path included. The domain alone is not enough.

DNSDomain Name System: finds which server a domain points to.

Status codeThe machine's verdict: 2xx worked, 4xx your mistake, 5xx theirs.

AbstractionHiding detail so you work at a higher level. Comfort that costs understanding.

SDKA provider's code wrapped around address, action, key and package.

Environment variableWhere keys live, outside your code, so they never reach a screenshot.

Rate limitRequests allowed per minute or day. Groq free: 30 per minute.

JQLJira Query Language, which the plan suggested for pulling Aarav's tickets.

18Before You Start the Next Lesson

Finish your observation if you have not: do your user's process by hand and write the golden pair. Everything below depends on it.
Run the raw request in httpie.io/app. POST, full endpoint, your key, a working model. Predict the status code first.
Rebuild section 13 for your own observation (or Aarav's), with your prompt and your user's real input.
Check one output against your golden pair and write one prompt change the check forced.
Screenshot the working app with your user's real input and the reply visible, key hidden. Keep it with your verification note.

On a customer site, nobody hands you the SDK that fits. The four questions get you into whatever system they already run.

Use abstractions for comfort. Build understanding for control.Practice set · Troubleshooting