What is an API?
API stands for Application Programming Interface. In simple terms, it's a contract that defines how two pieces of software talk to each other. A REST API specifically is a web API that follows a set of conventions — called REST (Representational State Transfer) — for how requests and responses are structured.
Think of a REST API like a restaurant: you (the client) give your order (request) to the waiter (API), who takes it to the kitchen (server) and brings back your food (response). You don't need to know how the kitchen works — you just need to know the menu (the API's documentation).
HTTP Methods: The Verbs of the Web
REST APIs use standard HTTP methods to indicate what action should be performed. These map directly to the four fundamental data operations (CRUD).
| HTTP Method | CRUD Operation | Example |
|---|---|---|
| GET | Read | GET /users — fetch all users |
| POST | Create | POST /users — create a new user |
| PUT | Update (full) | PUT /users/42 — replace user 42 |
| PATCH | Update (partial) | PATCH /users/42 — update specific fields |
| DELETE | Delete | DELETE /users/42 — delete user 42 |
JSON: The Language of APIs
Most REST APIs communicate using JSON (JavaScript Object Notation). JSON is a text format that represents data as key-value pairs, arrays, and nested objects. If you know JavaScript objects, you already know JSON — the syntax is nearly identical.
// A typical API response for GET /users/42
{
"id": 42,
"name": "Alex Johnson",
"email": "alex@example.com",
"role": "admin",
"createdAt": "2024-01-15T10:30:00Z",
"profile": {
"bio": "Full-stack developer",
"location": "Toronto"
},
"skills": ["JavaScript", "React", "Node.js"]
}HTTP Status Codes: What the Server is Telling You
| Code Range | Meaning | Common Examples |
|---|---|---|
| 2xx | Success | 200 OK, 201 Created, 204 No Content |
| 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 API issues, the status code is your first clue. A 401 means you're not authenticated. A 403 means authenticated but not authorized. A 404 means the resource doesn't exist. A 500 means something broke on the server.
Calling an API from JavaScript
// GET request — fetch data
async function getUser(id) {
try {
const response = await fetch(`https://api.example.com/users/${id}`);
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`);
}
const user = await response.json();
return user;
} catch (error) {
console.error("Failed to fetch user:", error);
}
}
// POST request — send data
async function createUser(userData) {
const response = await fetch("https://api.example.com/users", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${token}` // if auth required
},
body: JSON.stringify(userData)
});
const newUser = await response.json();
return newUser;
}