Doors, Counters, and Contracts

Vera coordinates city transport for Riverport, and lately every meeting she sits in reaches a point where someone says the word: the bike-share has an API, the parking system has an API, the new vendor's product "integrates via API." Everyone nods. Vera nods too. This book begins by retiring that particular nod, because the thing behind the word is not only understandable — it is one of the simplest ideas in computing, dressed up in an acronym.

An API — Application Programming Interface — is an agreed way for one program to ask another program for something and get an answer back. That is the whole definition. A promise, written down, about what you can ask and what you will get. The rest of this book is about reading those promises and using them, and none of it requires you to write a single line of code.

Interface Is an Everyday Word

Strip the acronym down and the mysterious part is the middle word, so start there. An interface is the agreed surface between you and something complicated. A light switch is an interface to the wiring in your walls: you know exactly what you can do with it — flip it up, flip it down — and you never have to touch a wire. The switch is a small, fixed set of allowed actions standing in front of a lot of hidden machinery.

You use interfaces all day without the word ever coming up. The pedals and steering wheel of a car. The buttons on a washing machine. In every case the pattern is the same: the complicated thing stays hidden, and you get a few well-defined ways to ask it for what you want.

Now Put It Between Two Programs

An API is that same pattern where both sides are software. Program A wants something — a list of bike stations, a weather forecast, a payment approved. Program B has it. The API is the agreed set of questions A may ask and the agreed shape of the answers B will give. Agreed in advance, fixed, and — this is the part that matters — written down where anyone can read it.

Think of a service counter with a printed menu of forms on the wall. Hand in form A at the counter, you get document B back. The menu tells you exactly which forms exist and what each one gets you. What happens in the office behind the counter is none of your business — and that is a feature, not an insult. The clerk's office can be reorganized completely, and as long as the counter honors the same forms, you never notice.

The Promise Is Written Down

Here is the fact that dissolves most of the fear. The agreement lives in documentation — ordinary web pages, published by whoever runs the API, listing which addresses exist, what to send to each one, and what comes back. Nothing about it is secret. There is no handshake to know, no club to join. The entire arrangement is designed to be read by strangers, because strangers reading it is how the API gets used at all.

When a developer says they "integrated with the payments API," here is what they actually did: read the documentation, sent the requests it describes, and handled the answers it promised. You will do the same thing in this book — reading real documentation in Chapter 6, sending real requests long before that.

What This Book Will Do

By the last chapter you will find an API's documentation, get yourself a key to it, send requests with tools already on your computer, read the answers, and work out — calmly — whose fault an error is. The tools are the web browser you already use and one small command-line program. No programming is taught or required anywhere in this book, because using an API is not programming. It is asking well.