What is an API?
How client-server communication works, REST, JSON, and why APIs exist
Skills taught: api.what-is-api, api.client-server, api.rest-concepts, api.json-data
How client-server communication works
Client (Browser/App) Server (API)
│ │
│── GET /users/42 ──────────────────> │
│ Host: api.example.com │
│ Accept: application/json │
│ Authorization: Bearer <token> │
│ │ ← looks up user 42
│ <─────────────── 200 OK ───────────│
│ Content-Type: application/json │
│ { │
│ "id": 42, │
│ "name": "Alice", │
│ "email": "alice@example.com" │
│ } │
// A REST API exposes resources at URLs
// The GitHub API (real example):
const BASE_URL = 'https://api.github.com';
// Resources and their endpoints:
// GET /users/{username} → get a user
// GET /repos/{owner}/{repo} → get a repository
// GET /repos/{owner}/{repo}/issues → list issues
// POST /repos/{owner}/{repo}/issues → create an issue
// PATCH /repos/{owner}/{repo}/issues/{number} → update issue
// DELETE /gists/{gist_id} → delete a gist
// JSON — the universal data format for APIs:
const user = {
id: 42,
login: 'alice',
name: 'Alice Smith',
public_repos: 24,
followers: 180,
created_at: '2018-03-15T10:00:00Z',
};
// Common API response patterns:
const singleResource = { id: 1, name: 'Alice' }; // one item
const listResponse = {
data: [{ id: 1 }, { id: 2 }], // array of items
total: 50,
page: 1,
per_page: 10,
};
const errorResponse = {
error: 'NOT_FOUND',
message: 'User 42 not found',
status: 404,
};
Frequently Asked Questions
What's the difference between an API and a REST API?
API (Application Programming Interface) is a general term — it just means an interface for two pieces of software to communicate. REST (Representational State Transfer) is a specific *style* of designing web APIs. A REST API uses HTTP, treats data as resources at URLs, and uses HTTP methods (GET/POST/PUT/DELETE) as actions. Most web APIs are REST APIs, but you'll also encounter GraphQL APIs, gRPC services, and WebSocket APIs.