What Is an API: API vs Web Page, REST Basics, and HTTP Status Codes
"API" is one of the most common words developers use, yet for people new to web development it is often a term heard but never fully explained. This article uses a restaurant analogy to explain what an API is, how it differs from a web page, and what REST means.
1. What an API Is: The Restaurant Waiter
Imagine walking into a restaurant. You do not go into the kitchen to cook for yourself. You tell the waiter what you want, the waiter relays your order to the kitchen, and the kitchen sends the finished dish back to you. An API is that waiter — a mutually agreed "communication window" between two pieces of software. One side makes a request, the other responds according to the rules, and neither needs to know how the other works internally.
For example, when you open a weather app, the app itself has no weather data. It calls the weather provider's API, sends a request for "today's weather in Shanghai", receives a data payload, and renders it into a nice interface. The app and the weather provider talk to each other through an API.
2. How an API Differs from a Web Page
Both web pages and APIs move data over the internet, but their purposes are completely different:
| Aspect | Web Page | API |
|---|---|---|
| Audience | Humans | Programs |
| Returns | HTML page (with styling, layout) | Structured data (usually JSON) |
| Access | Open a URL in a browser | A program sends a request and parses the reply |
| Example | Reading a blog post page | Querying a product stock endpoint |
The key difference: a web page answers "what should the page look like", while an API answers "here is the data itself". Many APIs can be opened in a browser address bar too, but you will see a messy blob of JSON because the browser does not format it for you.
3. REST Basics: The Four Most Common Methods
REST (Representational State Transfer) is the most common API design style. It treats data as "resources" and uses HTTP methods to express operations on those resources. The four most common methods:
| Method | Purpose | Analogy |
|---|---|---|
| GET | Read a resource | Read the menu |
| POST | Create a resource | Place an order |
| PUT | Fully update a resource | Change an order |
| DELETE | Delete a resource | Cancel a subscription |
For a blog system: GET /articles lists articles, POST /articles publishes a new one, PUT /articles/5 updates article 5, and DELETE /articles/5 deletes it. To learn API design rules in depth, see RESTful API Design Best Practices.
4. What a Request and a Response Look Like
One API call consists of a "request" plus a "response". A request usually contains four parts:
- URL: who the request goes to, e.g.
https://api.example.com/articles/5; - Method: what operation to perform (GET/POST/PUT/DELETE);
- Headers: extra information such as credentials or the expected response format;
- Body: the data being submitted, usually JSON for POST.
A response has two parts: a status code and the returned data. The most common data format is JSON. A weather API might return:
{
"city": "Shanghai",
"temperature": 31,
"condition": "Cloudy",
"updated_at": "2026-08-12T12:00:00+08:00"
}
The program parses this JSON field by field and displays it. That is a complete API interaction. To see how a backend endpoint is actually written, check Building a Node.js API Example.
To try it yourself, the simplest way is to open a terminal and run curl: curl 'https://api.example.com/weather?city=shanghai'. Press Enter and the terminal prints the returned JSON. If you prefer not to use the command line, a GUI tool like Postman makes sending and inspecting requests easier — see Postman API Testing.
5. HTTP Status Codes: Tell Success from Failure at a Glance
Status codes are three-digit numbers that tell the caller how the request went. Remembering three ranges is enough:
| Range | Meaning | Common Examples |
|---|---|---|
| 2xx | Success | 200 OK, 201 Created |
| 3xx | Redirect | 301 Moved Permanently, 304 Not Modified |
| 4xx | Client error | 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found |
| 5xx | Server error | 500 Internal Server Error, 503 Service Unavailable |
When debugging an API problem, reading the status code first saves half the effort: a 4xx usually means something on your side, so check parameters and credentials; a 5xx means the server side is at fault, so wait and retry. For step-by-step troubleshooting, see API Error Handling Guide.
6. FAQ
Q1: Do APIs have to use JSON? No. JSON is just the most common format. XML and plain text exist too, but JSON is the de facto standard because it is easy to read and works across languages.
Q2: Do I have to pay to call an API? It depends. Many services offer a free tier and charge by request count or traffic beyond it — weather, translation, and map APIs usually have free tiers. Always read the pricing page before integrating.
Q3: I cannot access an API, what do I do? First check whether rate limits or authentication are required (many APIs need an API key), then confirm the domain is reachable, then look at whether the error is 4xx or 5xx.
Q4: Is REST the only API style? No. There are also GraphQL, gRPC, and WebSocket. REST is the simplest and most universal, so it is ideal for beginners. For other styles, see REST vs GraphQL.
7. Summary
One line to remember: an API is an agreed communication window between two programs — web pages are for humans, APIs are for programs, REST uses four methods for CRUD, and status codes tell you instantly whether a call succeeded or failed. For more on backend integration, bookmark the Backend Integration category.