Transcript
Narration uses an AI-generated voice.
[00:00] Where we're going
By the end of this video, you'll be able to explain what an API is. It's a contract between two programs. And you'll know the four things that contract spells out.
[00:11] A contract between programs
API stands for application programming interface. It's a contract between two programs. One side promises: send me a request shaped like this, and I'll answer with a response shaped like that. The program that asks is the client. The one that answers is the server. The client relies on the promise, and ignores everything behind it.
[00:35] What the contract says
So what does the contract actually say? For each operation, a web API names four things. First, the address. That's a method and a path, like GET slash notes slash one. Second, what to send. Headers, and a body in an agreed format. Usually, that's JSON. Third, what comes back. A status code, and a body of a known shape. And fourth, what can go wrong. Which status codes mean which failure.
[01:10] Watch it happen
Let's watch that contract at work. A small notes API is running on this machine, and the terminal is the client. We ask for note one. Back comes two hundred, OK. The request worked. And the body has the promised shape: an id, and some text. Now we ask for a note that doesn't exist. This time it's four oh four, Not Found. That's a failure the contract names, so the client knows exactly what happened.
[01:40] Why a contract matters
One API can serve many different clients. A web page, a phone app, and a script can all call the same API. Each one only needs the contract. None of them needs to know how the server works inside.
And that's why the contract matters. It lets each side change on its own. The server can move to a new database. It can even be rewritten in another language. No client notices, as long as the requests and responses keep their shape.
[02:12] Breaking the contract
The flip side matters just as much. Breaking the contract breaks every client at once. Say someone renames a field in a response, just to tidy up the code. That's not a tidy-up. It's a change to the promise, and every client that reads the old name stops finding it.
That's why public APIs publish their contract as reference docs. And when the shape has to change, they add a new version, rather than change an old one.
[02:44] On ComputeSphere
On ComputeSphere, the console is a client of the ComputeSphere API. So is the command-line tool. And the contract they both rely on is the API reference.
[02:56] Recap
So, a quick recap. An API is a contract. The client asks, and the server answers. The contract names the address, what to send, what comes back, and what can go wrong. Keep the shape, and each side can change on its own. Change the shape, and every client breaks.
Here's a question to check yourself. A developer renames a response field, to match the rest of the code. What happens? Every client that reads the old name breaks. The rename changed the contract. Next, you'll see how REST and JSON shape that contract. I'll see you in the next lesson.