API Calls

What is an API call?

Open a weather app and it shows 14°C for your city. That number was not baked into the app when you installed it, and it changes by the hour, so where does it come from? The app asks a server for it, every time you open the screen. That request is an API call.

Most of what an app shows does not live inside the app. Your profile photo, the prices in a store, the weather on your lock screen, the unread badge on an inbox, none of it ships with the app; it sits on a server and gets fetched. The frontend sends a request over the network (the same kind of request your browser makes when it loads a page), the server does its work, and it sends back a response, usually as JSON, a plain-text format for structured data that JavaScript can read straight into an object. The browser has a built-in function for making that request: fetch(). You give it a URL, it sends the request, and it hands you the response when the server answers.

Think of it like ordering at a restaurant. You never walk into the kitchen; you give your order to a waiter, who carries it back and returns with the dish. The kitchen is the server, the order is your request, the dish is the response, and the menu is the set of things you are allowed to ask for. Two things about that trip matter more than beginners expect: it takes time, and sometimes the kitchen is out of the salmon. A request can come back slowly, and it can come back with nothing at all.

Why it matters

Almost every real app runs on data it fetches. Open a social feed and every post in it arrived from a server a moment before you saw it. Learn to fetch data and you can build the part of the frontend that actually does something.

The catch is the round trip. Reading a value already in your code is instant and certain; a fetch is neither. It travels out over a network you do not control and comes back later, or slowly, or not at all. So a screen that fetches data is really four screens: before the request, during the wait, on success, and on failure. Beginners build the third one and forget the other three, and the gaps below are what users hit first.

The four request methods

Every API call carries a method: one word that tells the server what you want done. Four of them cover almost everything you will do:

• GET reads data that already exists, without changing it (load the comments on a post).
• POST creates something new (post a new comment).
• PUT updates an existing item with new values (edit that comment).
• DELETE removes an item (delete that comment).

GET only reads; the other three change data, so they only work against a server built to accept those changes. The demo below sticks to GET, the request every app makes most and the easiest one to watch happen.

How it works

Type a name or ID and hit Fetch. Flip on Simulate Slow Network to stretch the loading state long enough to actually watch it, and use the reset icon to drop back to idle. Two things move together: the line under the search bar says in plain words what is happening, and its color tracks the state, grey when idle, amber while loading, green on success, red on error. The Network Inspector beside it shows the raw request, the same information your browser’s DevTools Network tab would.

That color-changing line is the whole lesson in miniature. Every fetch moves through four states, the four screens from “Why it matters” seen from the request’s side, and the demo makes you visit each one on purpose: idle is the screen before anyone asks for data, loading is the wait, success is the happy path that is easy to remember, and error is the 404, the dropped connection, the mistyped name. Ship only success and your UI shows a blank box on a slow network and a dead screen when the server is down.

The URL the inspector shows is an endpoint, an address that names one thing on the server: /pokemon/pikachu returns Pikachu’s stats, /users/42 returns user #42. An API that organizes its data into addresses like these is called a REST API, and it is by far the most common kind you will meet.

Turning that red error line into something a user can recover from, a retry button or a message that explains what went wrong, is its own topic, and it is where a future Error Handling page will pick up.