How APIs Work
Task: Follow one request from an app to a database and back
Why apps need APIs
Analogy
- Open a weather app and it shows you today's temperature.
- That temperature is not stored on your phone. Your phone has no idea what the weather is.
- It lives on a computer somewhere else, along with the weather for every other city.
- So your phone has to ask for it. An API is how it asks.
Almost every app you use does this. Instagram asks for your feed. A payment app asks whether the card is valid. A food app asks which restaurants are near you. In each case the app is small and the data is somewhere else.
What is an API?
Definition
An API is an agreement between two programs about how to ask for things.
It says: send your request to this address, in this shape, and you will get an answer back in that shape.
The letters stand for Application Programming Interface, which is not a helpful name. Think of it as a door with rules.
The best way to picture it is a restaurant.
You sit down and you want food. You do not walk into the kitchen, find a chef and start giving instructions. You tell the waiter. The waiter takes your order to the kitchen and brings the food back.
The waiter is the API. You never see the kitchen, and you do not need to. You only need to know how to order.
Note
An API is not a program or a server. It is the agreement about how to talk to one. That is why two completely different apps, written in different languages, can both use the same API.
What a request actually looks like
Here is the part that surprises people: a request is just a line of text.
GET /weather?city=Delhi
That is it. No magic. Three pieces, and the reply has two.
Read it out loud and it makes sense: get me the weather for the city Delhi.
The reply comes back the same way, as text:
{"city": "Delhi","temp": 31,"condition": "Clear"}That format is called JSON. It is just names and values, and almost every API answers in it.
The full journey
Now follow one request the whole way. The animation at the top of this page walks exactly these steps, one at a time.
Your app sends a request to the API
The API checks it and passes it to the server
The server asks the database for the data
The database sends the data back to the server
The server turns it into JSON
The reply travels back through the API to your app
Notice that the reply comes home through the same stops it went out through, in reverse. Nothing skips ahead.
The whole trip usually takes a fraction of a second. When an app shows you a spinner, this is what it is waiting for.
Why not just read the database?
This is a fair question. The database has the data. Your app wants the data. Why put two things in the middle?
Because the database would then have to trust whoever asked.
Anyone who got hold of the app could read anything in it: other people's orders, other people's messages, everything. The API is the part that asks who are you and are you allowed to see this before anything is handed over.
Watch out
There is a second reason, and it shows up later. If every app talked straight to the database, changing the database would break every app at once. With an API in the middle you can rebuild everything behind it, and as long as the door keeps the same shape, nothing outside notices.
The four requests you will see most
A request says what it wants to do, not just what it wants. That word at the front is the method.
| Method | What it means | Example |
|---|---|---|
| GET | Give me something | Fetch a user's profile |
| POST | Here is something new | Create a new account |
| PUT | Change something that exists | Update a delivery address |
| DELETE | Remove something | Delete a saved card |
GET is by far the most common. Most of what an app does is ask for things it does not have yet.
What the number in the reply means
Every reply starts with a status code. You only need to remember the first digit.
| Code | Meaning | In plain words |
|---|---|---|
| 200 | OK | It worked, here is your answer |
| 201 | Created | Your new thing was saved |
| 400 | Bad Request | You asked for it wrong |
| 401 | Unauthorized | I do not know who you are |
| 404 | Not Found | There is nothing at that address |
| 500 | Server Error | Something broke on our side |
A 4 at the front means the problem is with the request. A 5 means the problem is with the server. That one distinction saves a lot of time when something goes wrong.
An app tries to load a user's saved addresses and gets back 401.
- Whose fault is it, the app's or the server's?
- What is the most likely cause?
Show answerHide answer
- The app's. A 4 at the front means the request was the problem.
- The app did not send a valid login token, so the API had no way to know who was asking. It refuses rather than guessing.
Where the pieces fit
| Part | What it does |
|---|---|
| Your app | Asks for data it does not have |
| API | Takes the request, checks it, and brings the answer back |
| Server | Does the actual work of finding or changing the data |
| Database | Stores the data, and only talks to the server |
In a small project the API and the server are often the same program. They are drawn apart here because they are two different jobs, and it is much easier to put them together later than to tell them apart for the first time.
Quick recap
Whenever an app shows you something it could not possibly have stored, an API went and fetched it.
- Your app sends a request, which is a line of text
- The API checks it and passes it on
- The server gets the data, usually from a database
- The answer comes back as JSON with a status code
- Your app shows it
Key takeaway
An API is an agreed way for one program to ask another for something. The app asks, the API carries the request, the server does the work, and the answer comes back the same way it went out.