MAD-1: Modern Application Development
Week 6 Notes — REST and APIs
IIT Madras BSc Degree Programme
1. Distributed Software Architecture
Modern web applications operate across a distributed architecture where components —
clients, servers, and networks — are physically separated and must communicate through
standardised protocols. Before designing any system, certain foundational questions must be
answered:
• Is the server always on, or can it go down unpredictably?
• Does the server know what the client is currently doing or viewing?
• How is the client authenticated? Is the identity verified per-request or assumed from
context?
• What are the network latency characteristics? Can a slow or lossy network affect
correctness?
These are not merely engineering concerns — they shape the entire architecture of the system.
REST was designed precisely to address these challenges.
2. The Web as a Distributed Environment
The Web introduces specific challenges that traditional local-network assumptions break down
against:
• Client and server may be separated by many hops across different networks, with highly
variable latency and reliability.
• Authentication is not a core part of HTTP itself — it must be layered on top.
• State is ambiguous in both directions:
◦ The server cannot know which page or screen the client is currently on.
◦ The client cannot be certain that the server has not rebooted or switched instances
since the last request.
This stateless, heterogeneous nature of the web is the reason why specialised architectural
guidance was needed.
3. REST — REpresentational State Transfer
3.1 Origin
REST was introduced by Roy Fielding in his 2000 PhD thesis at UC Irvine. Fielding was one of
the principal authors of HTTP, so REST grew directly out of his experience designing the Web's
core protocol.
REST stands for REpresentational State Transfer. It is a software architecture
Key Point style — a set of guidelines and constraints — not a rigid protocol or standard.
Compliance is flexible; there are no hard enforcement rules.
3.2 What Does "Representational State Transfer" Mean?
The name describes exactly what happens during client-server communication:
• Every message explicitly carries the state information needed for that interaction.
• The client sends its current state (what it wants to do) to the server.
• The server responds with a representation of a resource plus any new state information
(e.g., new links to follow, updated resource URIs).
• Because each request is self-contained, neither side needs to silently remember the
other's context.
4. The Six REST Constraints
Fielding described REST as a set of constraints applied to distributed hypermedia systems.
Meeting these constraints yields the properties (scalability, reliability, simplicity) that the Web
requires.
Constraint 1: Client-Server
Responsibilities are clearly separated:
• Clients: handle user interaction, display, and trigger requests. Clients do not store data
persistently.
• Servers: store data, provide data on demand, and may perform computations.
• Network: acts as a passive data pipe. It connects clients to servers and must not alter or
interpret data in transit.
This separation of concerns allows clients and servers to evolve independently as long as the
interface between them remains stable.
Constraint 2: Stateless
Each request from client to server must contain all the information needed to understand and
process that request. The server cannot rely on any session state stored between requests.
• Server cannot assume: "this request is coming from a user who was already logged in
based on their address."
• Server cannot assume: "this client is on page 3 of a multi-step wizard."
• Client cannot assume: "the server I talked to 5 seconds ago is the same server handling
this request."
• Client cannot assume: "the server has not rebooted since my last request."
Statelessness enables horizontal scaling — any server in a pool can handle any
Why It
Matters
request because no session affinity is required. It also improves reliability since
failed requests can be retried freely.
Constraint 3: Layered System
A client does not need to know whether it is communicating directly with the end server or with
an intermediary. The architecture can include multiple layers:
• Load Balancers / Proxy Frontends: receive client requests and distribute them.
• Authentication Servers: validate credentials before forwarding to the backend.
• Pool of Backend Servers: the actual data-processing layer.
Clients interact only with the immediate layer; the internal topology is invisible to them. This
enables modular upgrades, security enforcement at boundaries, and transparent scaling.
Constraint 4: Cacheability
Responses must be labeled (implicitly or explicitly) as cacheable or non-cacheable. If a
response is cacheable:
• A proxy or the client itself can store that response and reuse it for equivalent future
requests.
• The backend server is never contacted for those repeated requests.
• This dramatically reduces server load and improves perceived performance for clients.
Example: A proxy in front of a Wikipedia API can cache the response for 'GET /page/Earth'. For
the next 1,000 users asking for the same page, the backend is not touched at all.
Constraint 5: Uniform Interface
This is the central, defining constraint of REST. All interactions between client and server follow
a predictable, standardised interface. There are four sub-principles:
• Resource Identification: resources are identified by URIs (e.g., /users/42).
• Manipulation Through Representations: the client manipulates a resource by sending a
representation (e.g., JSON body) along with the HTTP method.
• Self-Descriptive Messages: each message contains enough information to describe how
to process it (content-type headers, etc.).
• HATEOAS (Hypermedia as the Engine of Application State): the server's responses
include hypertext/links that tell the client what actions are available next. The client
discovers the API dynamically from the server's responses rather than hardcoding URLs.
Constraint 6: Code on Demand (Optional)
The server can extend or customise the client's functionality by sending executable code.
Classic examples:
• JavaScript sent in HTML pages that execute in the browser.
• Java applets (historically).
This is the only optional constraint. Many REST implementations omit it entirely.
5. The REST Communication Sequence
A typical REST interaction follows these steps:
• Step 1 — Client accesses a Resource Identifier from the server (usually a URI, which is
a superset of a URL). The client typically starts from a known entry point (e.g., the home
page). No prior state is assumed.
• Step 2 — Resource Operation: the client specifies what it wants to do with the resource.
In HTTP, this is the verb: GET, POST, PUT, DELETE, PATCH, etc. REST is not
fundamentally tied to HTTP, but HTTP is the standard carrier.
• Step 3 — Server responds with a new Resource Identifier or representation. This
response encodes the new state of the system — updated data, new links to follow,
confirmation of deletion, etc.
State of the interaction is transferred back and forth in each message, rather
Core Idea than stored implicitly on either side. This is the literal meaning of
"Representational State Transfer."
6. HTTP as a Carrier for REST
6.1 HTTP Verbs and Their Meaning
HTTP provides a standard vocabulary of verbs (methods) that map naturally to REST resource
operations:
Verb Operation Description
GET Read Retrieve a representation of the target resource's
state. Read-only; never modifies data.
POST Create / Process Enclose data in the request body; the server
processes it. Typically used to create a new
resource under a collection.
PUT Create / Replace Create or fully replace the target resource with the
enclosed data. The URI is chosen by the client or
known in advance.
DELETE Delete Remove the target resource. Subsequent DELETEs
return an error but leave data unchanged.
PATCH Partial Update Apply partial modifications to a resource, as
opposed to PUT which replaces entirely.
6.2 Idempotent Operations
An operation is idempotent if applying it multiple times has the same effect as applying it once.
This is important because networks can fail and requests may be retried.
• GET is idempotent (and safe): repeated reads never modify data. Always safe to retry.
• PUT is idempotent: sending the same PUT request twice results in the same resource
state. The second call may return an error ("already exists"), but the data is unchanged.
• DELETE is idempotent: deleting a resource once removes it. Calling DELETE again
produces an error ("not found") but does not corrupt data. The end state is the same.
• POST is NOT necessarily idempotent: posting the same "add comment" request twice
creates two comments. Retrying a POST blindly can cause duplicate entries.
Practical When designing retry logic in clients, idempotent methods (GET, PUT, DELETE)
can be retried automatically on network failures. POST requests must be
Implicatio
n
handled with care to avoid duplication — often requiring server-side
deduplication tokens.
7. CRUD and REST
CRUD stands for the four fundamental database operations: Create, Read, Update, Delete.
These map naturally onto HTTP methods:
CRUD Operation HTTP Method Example URI
Create POST POST /students (create new student)
Read GET GET /students/42 (get student with
id 42)
Update PUT / PATCH PUT /students/42 (replace student
record)
Delete DELETE DELETE /students/42 (remove student)
Important distinction: REST ≠ CRUD. REST is an architectural style applicable to any resource
operation; CRUD is a specific set of data operations. They work well together, but REST can
describe operations far beyond simple database CRUD (e.g., "reboot a virtual machine", "send
a notification").
8. Data Encoding in REST APIs
8.1 The Serialisation Problem
HTTP transmits data as text. However, application data (objects, arrays, nested structures)
must be serialised into a text format for transport, then deserialised on the other end. Several
formats are used:
• Basic HTML: suitable only for simple, human-readable responses. Not practical for
machine-to-machine APIs.
• XML (eXtensible Markup Language): structured, verbose, strongly typed. Common in
older enterprise APIs (SOAP).
• JSON (JavaScript Object Notation): simpler, lighter, widely adopted. The dominant
format for modern REST APIs.
• YAML (Yet Another Markup Language): human-readable alternative to JSON/XML.
Commonly used for configuration files and API documentation (e.g., OpenAPI specs).
8.2 JSON — JavaScript Object Notation
JSON represents data as key-value pairs and nested arrays/objects. It can serialise complex
data structures including:
• Strings, numbers, booleans, null
• Arrays (ordered lists)
• Objects (dictionaries / maps)
• Deeply nested combinations of all of the above
Example JSON object representing a person:
{
"firstName": "John",
"lastName": "Smith",
"age": 27,
"address": {
"streetAddress": "21 2nd Street",
"postalCode": "10021-3100"
},
"phoneNumbers": [
{ "type": "home", "number": "212 555-1234" },
{ "type": "office", "number": "646 555-4567" }
],
"children": [],
"spouse": null
}
8.3 API Data Transfer Format — Key Distinctions
Three different representations exist for the same data in a web application:
• API Transfer Format (JSON/XML): what is sent over HTTP between client and server.
Optimised for machine parsing.
• Internal Server Representation: how the server stores/processes data internally (e.g.,
Python objects, database rows). Not exposed to clients.
• Final View Presentation: the HTML/CSS rendered to the user's browser. Not what the
API returns.
Understanding these three layers prevents confusion — a REST API returns data in JSON, not
rendered HTML.
9. REST API Examples
9.1 Typical REST API Functionality
Most REST APIs provide some combination of:
• CRUD operations on data resources.
• Listing and filtering variants (e.g., GET /students?course=CS101).
• Specialised domain operations: create a virtual machine, reboot a server, turn off street
lights on a specific road.
• Formal specifications that allow third parties to build clients without knowing
implementation internals.
9.2 Example: Wikipedia REST API
Wikipedia exposes a public, open REST API built on MediaWiki:
• Search for pages by keyword.
• Retrieve page history (revisions with timestamps, authors, sizes, diffs).
• Output is JSON.
Example: Search for pages about "earth" (limit 1 result):
curl "[Link]
q=earth&limit=1"
Response JSON (abbreviated):
{ "pages": [{ "id": 9228, "key": "Earth", "title": "Earth",
"description": "Third planet from the Sun in the Solar System",
"thumbnail": { "url": "...200px-The_Earth_seen_from_Apollo_17.jpg" }
}] }
Example: Get page revision history:
curl [Link]
Response includes an array of revision objects, each with: revision id, timestamp, editor
username, byte size, edit comment.
The API documentation defines a schema for each response field. For example, the search
result schema specifies: id (integer, required), key (URL-friendly string), title (readable string),
excerpt (string with search-match span tags), description (string or null from Wikidata).
9.3 Example: CoWin Public APIs
India's Co-Win vaccine registration platform exposed a public REST API:
• Unauthenticated endpoints: search vaccination centres by state/district/pincode, check
availability.
• Authenticated endpoints: book appointments, download vaccination certificates.
Example: Find vaccination sessions by pincode and date:
GET /v2/appointment/sessions/public/findByPin
?pincode=600020&date=04-08-2021
The response JSON includes: center_id, name, address, state_name, district_name, pincode,
session timings, available_capacity, fee, vaccine type, etc.
If required parameters are missing, the API returns an error object:
{ "errorCode": "USRRES0001", "error": "Input parameter missing" }
When testing public APIs, always use them sparingly. Sending high volumes of
Warning automated requests to a public API is rate-limited, potentially illegal, and
unethical — it consumes server resources funded by others.
10. Authentication in REST APIs
10.1 Why Authentication?
Many APIs need to restrict access for two reasons:
• Access Control: the API is only meant for specific authorised users (e.g., only you can
book your vaccine appointment).
• Abuse Prevention: open APIs without limits can be overloaded by bots or abusive
scripts, causing denial-of-service for legitimate users.
10.2 Mechanisms
OAuth Tokens (e.g., Google OAuth, Facebook Login)
The user logs in through a trusted identity provider (Google, Facebook). Upon successful login,
the provider issues a short-lived cryptographic token. The client presents this token in every
subsequent API request (typically in the HTTP Authorization header). The server verifies the
token without needing to know the user's password.
API Keys
A one-time static token that the user downloads when they register for API access. It is included
in request headers or query parameters. Simpler than OAuth but less secure on its own — the
key can be copied and shared. Often combined with IP whitelisting, rate limiting, or HTTPS-only
transport for additional security.
The unauthenticated CoWin certificate download endpoint demonstrates the risk of missing
authentication — accessing it without a token returned a "Unauthenticated access!" error, which
is the correct behaviour; a misconfigured version would be a serious security vulnerability.
11. OpenAPI Specification (OAS)
11.1 The Problem with Documentation
Human-written API documentation has persistent problems:
• Highly subjective: different programmers document different things.
• Incomplete: what the author considers obvious is often missing.
• Outdated: code changes but docs do not get updated.
• Language-specific: English documentation is inaccessible to non-English-speaking
developers.
The solution: machine-readable description files that have a strict, formal structure.
11.2 Description Files vs. Human Documentation
A machine-readable description file:
• Has a precise, unambiguous structure that both humans and tools can parse.
• Enables automated code generation (client SDKs, server stubs, boilerplate).
• Enables mock server generation — a fake server that returns dummy data so frontend
developers can work before the backend is ready.
• Is analogous to assembly language: structured enough to be compiled/processed, yet
still readable by humans.
• Becomes a single source of truth: the code is derived from the spec, or the spec is auto-
generated from the code. This prevents documentation from diverging from
implementation.
11.3 OpenAPI History
OpenAPI Specification (OAS) was originally developed as the Swagger specification. It evolved
from Swagger 2.0 and is now maintained by the OpenAPI Initiative as a vendor-neutral format
for HTTP-based API specification. Current version: OAS3 (v3.1.0 as of August 2021). It does
not aim to cover all conceivable APIs but efficiently handles the most common cases.
11.4 OAS Structure — Building Blocks
An OpenAPI document is written in YAML (preferred) or JSON. It follows a strict hierarchical
structure:
Top-Level Structure
openapi: 3.1.0
info:
title: A minimal OpenAPI document
version: 0.0.1
paths: {} # No endpoints defined yet
Paths Object
The paths object lists every endpoint (URL path) the API exposes. Example for a Tic Tac Toe
API:
openapi: 3.1.0
info:
title: Tic Tac Toe
description: |
This API allows writing down marks on a Tic Tac Toe board
and requesting the state of the board or of individual squares.
version: 1.0.0
paths:
/board:
...
Path Item Object
Each path maps to a Path Item Object, which lists the HTTP methods supported on that path:
paths:
/board:
get:
...
put:
...
Operation Object
Each HTTP method maps to an Operation Object describing exactly what that operation does:
paths:
/board:
get:
summary: Get the whole board
description: Retrieves the current state of the board and the
winner.
parameters:
...
responses:
...
Responses Object
The responses field lists all possible HTTP status codes the operation can return:
responses:
"200":
description: Everything went fine.
content:
...
"404":
description: Resource not found.
...
Content Specification and Media Types
The content field specifies the format of request/response bodies. Multiple media types can be
supported:
content:
application/json:
...
text/html:
...
text/*:
...
Schema — Describing Data Types
A schema formally describes the shape and constraints of the data. Simple example (integer
with constraints):
content:
application/json:
schema:
type: integer
minimum: 1
maximum: 100
Complex object schema (e.g., a product with name and price):
schema:
type: object
properties:
productName:
type: string
productPrice:
type: number
Parameters
Parameters can appear in the URL path, query string, or headers. Example of a path parameter:
paths:
/users/{id}:
get:
parameters:
- name: id
in: path
required: true
The in field can be: path, query, header, or cookie.
Request Body
For POST/PUT operations, the request body is described separately from parameters:
requestBody:
content:
application/json:
schema:
type: integer
minimum: 1
maximum: 100
The Endpoints List Diagram
The overall structure can be visualised as a hierarchy: OpenAPI Object → Paths Object → (per
endpoint) Path Item Object → (per verb) Operation Object → responses → Responses Object
→ (per HTTP code) Response Object → description + content.
Slide 59 shows the OpenAPI object hierarchy as a diagram: OpenAPI Object >
Visual Paths Object > Path Item Object (get, put, post, delete...) > Operation Object
Aid (summary, description, requestBody, responses, operationId) > Responses
Object (HTTP code strings) > Response Object (description, content).
12. OpenAPI Best Practices
12.1 Design-First vs. Code-First
There are two approaches to building a REST API:
• Code-First: write the implementation, then generate or write the spec from the code.
Risk: the spec may lag behind or be incomplete.
• Design-First: write the OpenAPI spec first, then implement the server from it. This is the
recommended approach.
Why Starting with the spec forces explicit API design decisions before any code is
Design- written. It aligns teams, enables parallel frontend/backend development (via
First? mock servers), and creates a stable contract from day one.
12.2 Single Source of Truth
One of the most important rules in real-world API development:
• Either the code is derived from the OAS (code generation from spec), OR
• The spec is derived from the code (annotation-based spec generation).
• Whichever approach is chosen, there must be one canonical source. Having both a
manually maintained spec and a separate implementation that can drift apart is a major
source of bugs.
12.3 Other Best Practices
• Source code version control: treat the .yaml spec file like source code — commit it,
branch it, review changes via pull requests.
• Public documentation: publishing the OpenAPI spec publicly (like CoWin, Wikipedia)
allows the community to identify bugs, inconsistencies, and missing coverage.
• Use automated tools and editors: tools like Swagger UI, Redoc, and Stoplight can render
interactive API documentation directly from the YAML file, with live-testing features. IDE
plugins provide syntax checking and autocompletion for OAS files.
13. Summary and Key Takeaways
Concept Summary
REST Architectural style for distributed web systems (Fielding, 2000).
Not a protocol — a set of 6 constraints.
Stateless Each request carries all needed information. No implicit server-
side session memory.
HTTP Verbs GET (read), POST (create/process), PUT (create/replace),
DELETE (remove). Maps to CRUD.
Idempotency GET, PUT, DELETE are idempotent. POST is not. Retry-safe
design relies on this.
JSON Primary data serialisation format for REST APIs. Supports
nested objects and arrays.
Authentication Tokens (OAuth) or API Keys protect restricted endpoints from
unauthorised or abusive access.
OpenAPI / OAS Machine-readable YAML/JSON spec format for HTTP APIs.
Enables auto code-gen, mock servers, interactive docs.
Design-First Always write the OAS before implementing. Prevents spec-code
divergence and enables parallel dev.
End of Week 6 Notes — MAD-1 | IIT Madras BSc Programme