The path to AI FDE #07: APIs and JSON: how programs talk to each other

Originally published on my newsletter, The Path to AI FDE. Subscribe free to get each issue by email.

This is a “From Zero” issue. Yesterday (#06) we followed one request from a client to a server and back. Today is about what programs say to each other in those requests. The answer, almost always, is: they call an API, and they speak JSON. Every AI model you’ll use in this series is reached this way. No code to install today, just a toy café API and a browser.

Part A · Ordering from an API

1. An API is a menu that one program offers another. API stands for application programming interface. Picture a restaurant: the menu tells you what you can order, you write an order slip, the kitchen does the work out of sight, and a plate comes back. A web API is the same deal for software. A server offers a fixed set of operations, publishes exact rules for how to ask, and hides how it does the work. That last part matters: the kitchen can change its ovens as long as the menu stays the same. When your code “talks to” an AI model, it’s ordering from that provider’s API.

2. An endpoint is one address that does one job. Each item on the menu has its own URL, called an endpoint: https://api.example.com/v1/weather?city=Chennai breaks into a base URL, a version (/v1), a path (/weather) and an optional query string after the ?. The HTTP method says what to do at that address. In our toy café API:

• GET /v1/menu lists the menu;
• GET /v1/orders/1042 looks up one order;
• POST /v1/orders places a new one;
• DELETE /v1/orders/1042 cancels it.

The version in the path lets an API launch a changed /v2 without breaking code written for /v1.

3. The request body carries the data you’re sending. When you create or change something, usually with POST, PUT or PATCH, the details travel in the request body: the order slip itself. A header, Content-Type: application/json, tells the server the body is JSON. A GET, which only asks for something, normally has no body; its small options go in the URL instead. Calling an AI model is the same pattern: a POST whose JSON body holds your messages and settings.

Part B · JSON and the reply

4. JSON is plain text built from six kinds of value. JSON (JavaScript Object Notation) writes data as keys and values. The JSON standard (RFC 8259) defines four simple types and two containers:

• text (a string) in double quotes: "masala chai";
• numbers with no quotes: 2 or 4.5;
• true or false;
• null, a deliberately empty value;
• lists (arrays) of values in square brackets: ["ginger", "less sugar"];
• objects of key-value pairs in curly braces: {"name": "Asha"}.

Lists and objects can hold anything, including more lists and objects, so you can nest them like boxes. Despite the name, JSON isn’t tied to JavaScript; practically every language reads and writes it.

5. JSON is strict, and that’s a feature. One slip and a parser rejects the whole message, so programs never have to guess what you meant. The same handful of mistakes cause most failures:

• Double quotes only, for keys and text. Single quotes are an error.
• No trailing comma after the last item in a list or object.
• No comments. If you need a note, make it a real key and value.
• Lowercase true, false and null. True and None are Python, not JSON.
• Don’t quote numbers. "2" is valid JSON, but it’s text, so maths on it fails later. This is the sneaky one because nothing complains straight away.

6. The response is a status code plus a JSON answer. The plate comes back with a note saying how it went. Read the status code first:

• 200 OK or 201 Created mean it worked;
• 400 means your request was malformed;
• 401 means your credentials are missing or wrong;
• 404 means there’s nothing at that address;
• 429 means slow down;
• 500 and 503 mean the server is having a bad time.

Then read the body. A good API sends JSON even when things fail, and that error object usually tells you exactly what went wrong: "No order ord_9999".

7. The docs are the menu, so read them first. Good APIs publish documentation, and nearly all of it covers the same seven things:

• the method and URL;
• how to authenticate;
• the parameters, with their types and which are required;
• an example request;
• an example response;
• the errors it returns;
• the limits.

Most “it doesn’t work” moments turn out to be a field name, a type or a required header that the docs already mentioned. Many APIs also publish an OpenAPI file: the same menu in a format tools can read. Reading docs carefully is a core engineering skill, and a daily one for anyone who integrates systems for customers.

Try it (10 minutes, no code)

1. Write a JSON object for a book you like with five keys:
2. "title" (text);
3. "authors" (a list of text);
4. "pages" (a number);
5. "available" (true or false);
6. "rating" (null, because you haven’t decided yet).
7. Check it. Either paste it into any online JSON validator, or open your browser’s developer tools (F12), click Console, and type JSON.parse('...') with your JSON between the single quotes. If it’s valid, you’ll see the object; if not, you’ll get an error pointing at the problem.
8. Now break it on purpose, once for each rule in point 5, and read each error message.

Check your understanding: how many problems can you find in this?

{'city': "Pune", "temp_c": "31", "raining": False, }

(Answer: four. Single quotes around city; False should be false; there’s a trailing comma before }; and "31" parses but is text, not a number.)

Common beginner mistakes

• Using single quotes or trailing commas. Both are invalid JSON.
• Writing numbers in quotes ("5"), which turns them into text.
• Reading the body and ignoring the status code, or ignoring the error body when the status is bad.
• Guessing field names instead of opening the docs.

Takeaway

An API is a menu of operations. You pick an endpoint, send a JSON request body if you’re sending data, then check the status code and read the JSON that comes back. JSON has six kinds of value and strict rules, and docs tell you the rest.

Where this fits in my roadmap: this is on-ramp material, outside my current study block. I work with APIs and JSON daily as a TypeScript engineer, so I’m writing it for readers starting from zero. Section 3 picks it up with real code: calling a web API from Python, API keys and rate limits, then your first LLM API call.

Over to you: what’s an app on your phone that you now suspect is “just” calling an API? What would one of its endpoints be?

Sources

1. MDN: API (glossary). https://developer.mozilla.org/en-US/docs/Glossary/API
2. MDN: Introduction to web APIs. https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Client-side_APIs/Introduction
3. MDN: What is a URL? (scheme, domain, path, query parameters). https://developer.mozilla.org/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL
4. MDN: HTTP request methods and POST. https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods · https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods/POST
5. RFC 9110: HTTP Semantics (methods, message content, status codes in §15). https://www.rfc-editor.org/rfc/rfc9110
6. MDN: Content-Type header. https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Type
7. RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format (four primitive types and two structured types; strings in double quotes; lowercase literal names; the application/json media type). https://www.rfc-editor.org/rfc/rfc8259
8. ECMA-404: The JSON data interchange syntax. https://ecma-international.org/publications-and-standards/standards/ecma-404/
9. MDN: Working with JSON, and JSON.parse(). https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Scripting/JSON · https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse
10. MDN: HTTP response status codes; 201 Created; 429 Too Many Requests. https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status · https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/201 · https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429
11. RFC 6585: Additional HTTP Status Codes (429). https://www.rfc-editor.org/rfc/rfc6585
12. OpenAPI Specification (a standard, language-agnostic description of HTTP APIs). https://spec.openapis.org/oas/latest.html

The café API, its URLs, order ids and prices are made up for teaching. Sources checked Oct 31, 2026.

Free: the 5-page roadmap from Novice to AI FDE.

If this was useful, subscribe to The Path to AI FDE for the next issue.