The one-paragraph explanation
An API (Application Programming Interface) is a defined way for two software systems to communicate. A REST API follows architectural principles — REST (Representational State Transfer) — that make it predictable, scalable, and easy to use over HTTP. When your mobile app shows your bank balance, a REST API connected to your bank's servers.
How HTTP and REST work together
Every REST API interaction consists of a request and a response. The request has: a method (action to perform), a URL (resource to act on), headers (metadata including authentication), and an optional body. HTTP methods map to CRUD: GET retrieves, POST creates, PUT/PATCH updates, DELETE removes.
Resources and URLs: the grammar of REST
REST URLs should be noun-based: GET /users/123 not GET /getUser?id=123. Conventions: /resources for a collection, /resources/{id} for a specific item, /resources/{id}/sub-resources for nested relationships. Plural nouns, lowercase, hyphens for multi-word names.
Status codes: the language of responses
2xx Success: 200 OK, 201 Created, 204 No Content. 4xx Client Errors: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict. 5xx Server Errors: 500 Internal Server Error, 503 Service Unavailable. Using correct status codes lets clients handle errors correctly without parsing the response body.
Authentication patterns
API Keys — static secrets in headers, good for server-to-server. JWT — signed tokens with user claims, good for user-facing apps. OAuth 2.0 — the protocol behind Sign in with Google, for delegated access.
Designing an API that does not become a nightmare
Mistakes: inconsistent naming, verb-based URLs, different structures for the same resource. Best practices: consistent response envelope, consistent error format, pagination on every list endpoint, documentation generated from code.
