Introduction
An API (Application Programming Interface) defines how different pieces of software talk to each other. The most common style for web APIs today is REST (Representational State Transfer), which structures an API around resources — nouns like users, orders, or products — and lets standard HTTP verbs act on those resources. Good API design makes an API predictable, easy to learn, and safe to evolve, while poor API design leads to confusing endpoints and brittle client code.
Cricket analogy: An API is like the standardized signals between an umpire and the third umpire — REST specifically organizes those around 'reviews' (nouns) with fixed actions like request, check, confirm (verbs); a predictable protocol like DRS works the same across every match, while an ambiguous soft-signal system causes confusion.
Explanation
REST is built on a few key principles. First, everything is modeled as a resource, identified by a URL — for example /users represents the collection of users, and /users/123 represents one specific user with ID 123. Second, HTTP verbs map onto CRUD (Create, Read, Update, Delete) operations on those resources: GET retrieves a resource without changing it (Read), POST creates a new resource (Create), PUT or PATCH updates an existing resource (Update), and DELETE removes a resource (Delete). Third, REST APIs are stateless: each request from a client must contain all the information the server needs to process it (such as an auth token), and the server does not store any client session state between requests — this makes it easy to scale a REST API horizontally, since any server instance can handle any request. Finally, HTTP status codes communicate the outcome of a request in a standardized way, so clients can react correctly without parsing response bodies just to know if something worked.
Cricket analogy: Think of /players/18 as Virat Kohli's specific record — GET reads his stats (Read), POST adds a new player to /players (Create), PATCH updates his current form rating (Update), DELETE retires him from the active list (Delete); each request carries its own accreditation badge, so any gate can process any pass.
Example
from flask import Flask, jsonify, request
app = Flask(__name__)
users = {123: {"id": 123, "name": "Ada Lovelace"}}
@app.route("/users/<int:user_id>", methods=["GET"])
def get_user(user_id):
user = users.get(user_id)
if not user:
return jsonify({"error": "User not found"}), 404
return jsonify(user), 200
@app.route("/users", methods=["POST"])
def create_user():
data = request.get_json()
if not data or "name" not in data:
return jsonify({"error": "'name' is required"}), 400
new_id = max(users.keys()) + 1
users[new_id] = {"id": new_id, "name": data["name"]}
return jsonify(users[new_id]), 201
# GET /users/123 -> 200 with the user, or 404 if missing
# POST /users -> 201 with the created user, or 400 if invalidAnalysis
Status codes are grouped by their first digit and each specific code has a precise meaning that clients rely on. 200 OK means the request succeeded and the response body contains the result (typically for GET, PUT, or PATCH). 201 Created means a new resource was successfully created, typically returned by POST, often along with the new resource's data and a Location header. 400 Bad Request means the client sent invalid data — for example, a required field was missing — and the client should fix the request before retrying. 404 Not Found means the requested resource does not exist, such as GET /users/999 for a user ID that was never created. 500 Internal Server Error means something went wrong on the server itself — a bug or unexpected failure — and it is not the client's fault. Using the correct status code (rather than always returning 200 with an 'error' field in the body) lets clients, proxies, caches, and monitoring tools all reason about outcomes using a shared, well-understood vocabulary.
Cricket analogy: 200 OK is a run successfully scored and confirmed on the scoreboard; 201 Created is a new player officially added with a registration number; 400 Bad Request is a no-ball for an invalid front-foot delivery; 404 Not Found is searching for a player never in the squad; 500 Internal Server Error is the electronic scoreboard glitching through no fault of the batting team.
Key Takeaways
- REST models everything as resources identified by URLs, e.g. /users and /users/123.
- HTTP verbs map to CRUD: GET=Read, POST=Create, PUT/PATCH=Update, DELETE=Delete.
- REST APIs are stateless: each request carries all the information needed, with no server-side session state.
- 200 = success, 201 = resource created, 400 = bad client request, 404 = resource not found, 500 = server error.
- Using accurate status codes lets clients react correctly without parsing custom error fields.
Practice what you learned
1. In a REST API, which HTTP verb is conventionally used to create a new resource?
2. What does it mean for a REST API to be 'stateless'?
3. A client sends GET /users/999 for a user ID that does not exist. What status code should the server return?
4. A client sends POST /users with a missing required field. What status code best describes this situation?
Was this page helpful?
You May Also Like
Software Architecture Basics
An introduction to software architecture: the high-level structure of a system, its components, and how they interact.
Monolith vs Microservices
Compares monolithic and microservices architectures across deployment, scaling, communication, complexity, and failure isolation.
MVC Architecture Pattern
An architectural pattern that separates an application into Model (data), View (presentation), and Controller (input mediation) layers.
Software Documentation
Learn the major types of software documentation and how each serves a distinct audience and purpose.
Related Reading
Related Study Notes in Software Engineering
Browse all study notesMicroservices Study Notes
Software Architecture · 30 topics
Software EngineeringTesting & TDD Study Notes
Software Testing · 30 topics
Software EngineeringDesign Patterns Study Notes
Software Design · 30 topics
Software EngineeringGit & Version Control Study Notes
Bash · 40 topics
Software EngineeringSystem Design Study Notes
Architecture · 46 topics