The Core Idea
A Defined Contract Between Separate Programs
An API (Application Programming Interface) is a defined contract specifying how one piece of software can request functionality or data from another, without needing to know anything about that other system's internal implementation details — just what requests are available, what information they need, and what response to expect back. This is directly related to abstraction (from the 4 Pillars of OOP lesson), applied at the level of entire separate systems communicating with each other, rather than just one object calling another object's method.
REST (Representational State Transfer) is a specific, widely-adopted architectural style for designing web APIs, built around a small set of core principles that, followed consistently, produce predictable, well-organized APIs that are easier for other developers to understand and correctly use.
💡 Memory Trick
Think of a restaurant's printed menu as an API. The menu (the API contract) tells you exactly what dishes (functionality/data) are available to request, and what information you need to provide (like 'medium-rare' for a steak) — you don't need to know anything about the kitchen's internal cooking process to successfully order and receive your food. A RESTful menu specifically organizes dishes logically by clear category (appetizers, mains, desserts — analogous to REST's resource-based organization) and uses a small, consistent set of ordering actions (order, modify, cancel) that work the same predictable way across every single dish on the menu.
Core REST Principles
Resources, URLs, and HTTP Methods
1
Resources as Nouns
REST organizes an API around 'resources' — nouns representing the things the API manages, like 'users,' 'orders,' or 'products' — rather than organizing around verbs or specific actions. Each resource type typically gets its own URL pattern, like /users or /orders.
2
HTTP Methods Map to CRUD Operations
REST leans on the HTTP methods (from the CS Networking lessons) to express WHAT action to take on a resource, rather than encoding the action into the URL itself: GET /users retrieves users, POST /users creates a new user, PUT or PATCH /users/123 updates a specific existing user, and DELETE /users/123 removes a specific user — the same small set of HTTP verbs applied consistently across every resource type in the API.
3
Statelessness
Each individual request must contain all the information needed to be understood and processed on its own — the server doesn't rely on remembering anything from a PREVIOUS request to correctly interpret the current one. This makes RESTful APIs easier to scale horizontally (any server instance can handle any request, without needing shared memory of prior requests) and easier to reason about, since each request can be understood in isolation.
Why RESTful Design Is Valued
Predictability Through Consistency
The core benefit of following REST's conventions consistently is PREDICTABILITY: once a developer understands that GET retrieves, POST creates, PUT/PATCH updates, and DELETE removes, they can correctly guess how to interact with an unfamiliar RESTful API's /products or /invoices resources without needing to read extensive custom documentation for every single endpoint — the same small set of conventions applies uniformly across the entire API.
This predictability is exactly why REST became the dominant style for web APIs — an API that instead used inconsistent, ad-hoc URL and method conventions for every different resource (like /getUser, /createNewOrderNow, /removeProductFromCatalog) forces developers to learn each endpoint's specific quirky convention individually, rather than being able to apply one small, consistent mental model across the entire API surface.
🖥️ Applied Scenario
You're designing an API for a library management system that needs to support creating, viewing, updating, and removing book records.
1
You define 'books' as a resource, giving it a consistent URL pattern: /books for the overall collection, and /books/{id} for a specific individual book.
2
You map each required operation to the appropriate HTTP method: GET /books lists all books, GET /books/{id} retrieves one specific book, POST /books creates a new book record, PUT /books/{id} updates an existing book, and DELETE /books/{id} removes a specific book.
3
You ensure each request is fully self-contained — a request to update a specific book includes that book's ID and the new data directly in the request itself, without depending on the server remembering anything from an earlier request in the same session.
4
Conclusion: a developer who has never seen this specific API before, but who understands standard REST conventions, can correctly guess how to create, retrieve, update, and delete book records with minimal need to consult custom documentation, precisely because the API consistently follows the same widely-recognized conventions used across countless other RESTful APIs.
📌 Exam Application
Exam questions frequently ask you to design (or evaluate) a set of RESTful API endpoints for a described resource, expecting correct use of resource-based URLs and appropriate HTTP methods mapped to CRUD operations. You may also be asked to explain what statelessness means in a REST context and why it specifically benefits horizontal scalability.
⚠️ Most Common APIs and REST Mistakes
The most common mistake is encoding an ACTION into the URL itself (like /getUserById or /deleteOrder) rather than expressing the action through the appropriate HTTP method applied to a noun-based resource URL (like GET /users/{id} or DELETE /orders/{id}) — this violates REST's resource-based, verb-through-HTTP-method convention and produces an inconsistent, harder-to-predict API surface. Another frequent error is assuming statelessness means the server can't use a database or any persistent storage at all — statelessness specifically means the server doesn't rely on remembering context from a PREVIOUS individual request to correctly process the current one; the server can absolutely maintain a persistent database of resources, it just can't depend on in-memory session state carried over between separate, individual API calls.
✓ Quick Self-Test
Given a described resource (like 'comments' on a blog post), can you design a complete set of RESTful endpoints covering create, read, update, and delete operations, using appropriate HTTP methods and resource-based URLs? Can you explain what statelessness means in REST, and why it specifically benefits a system's ability to scale across multiple servers?
Next Lesson
Concurrency and Parallelism
→
← All Programming Concepts Lessons