API: How Software Talks to Software

An API is a promise: ask in the agreed shape, get an answer in the agreed shape, and never see the machinery behind it. The fastest way to understand one is to read a real exchange.

If the command line is the door for people, the API — application programming interface — is the door for software. One program asks another to do something, and the key idea is that you don't need to know how the other system works inside. You only honour its contract: send a request in the agreed shape, receive a response in the agreed shape. The internals stay hidden, which is exactly what lets two teams, or two companies, cooperate without coordinating every detail.

Here's a real exchange — a program asking a weather service for the temperature in Lima, and the service answering. A few lines each way, every part doing one job.

GET /v1/weather?city=Lima     # the verb (read) + what I want
Accept: application/json       # answer me in JSON

200 OK                        # it worked — a status code
{ "city": "Lima", "tempC": 22 }   # the data

That word at the front — GET — and the number that comes back — 200 — are the two things worth understanding. Start with the verb.

REST: the style that runs the web

Most APIs you'll meet follow REST, an architectural style Roy Fielding defined in his 2000 PhD dissertation — and he co-authored the HTTP specifications themselves, so this isn't an outsider theorizing. REST's move is elegant: instead of inventing new verbs, reuse the four that HTTP already has.

So GET /posts reads posts, POST /posts creates one, DELETE /posts/42 removes one. Once you internalize this pattern, you can guess how most web APIs work before reading a line of their docs — that's the power of a shared style. The 200 from earlier is part of the same agreement: a small family of status codes (200 worked, 404 not found, 500 server error) that every API shares.

Writing the contract down: OpenAPI

If an API is a contract, OpenAPI is that contract written in a machine-readable file. It began as “Swagger” in 2011 and became the OpenAPI Specification under the Linux Foundation in 2016. That file is what lets tools auto-generate documentation and client code — and, increasingly, what lets an AI understand an API without a human explaining it. Hold that thought: a machine-readable description of what a system can do, and how to call it, is exactly the bridge to the next door in this course.

Try this

Next time an app does something across the internet — loads your feed, sends a message, fetches a price — picture the request behind it. Which verb? What's the path? What comes back? You'll start seeing the web as a constant exchange of these small contracts, which is exactly what it is.

Sources — Roy Fielding, REST dissertation (2000); Wikipedia, REST and OpenAPI Specification.