Qs: BE REST API

---

REST API Basics

---

Vocab

RESTful conventions = RESTful Endpoint conventions

Resource = Data = Entities = Objects = Models = Domain Objects/Entities = Data Objects

→ i.e. List Resources = Get All Items In A Collection

Idempotent = Making the same request multiple times in a row has the same effect as making it once.

Safe = read-only operation = does not change the server’s state

HTTP verbs = HTTP methods = Request Methods = REST Verbs = HTTP Request Methods

HTTP Response Codes = HTTP Status Codes = Status Codes = HTTP Codes = Response Status Codes = Server Response Codes = REST API Status Codes

HTTP Headers = Metadata = Data About Data

REST API endpoints = Routes = Paths = URL Paths = API Paths = Resource URLs = API Endpoints

---

What Is The Essence Of A REST API ?

REST = Resources + Standard HTTP verbs + Statelessness + Uniform rules.

Data exposed as resources.

Uses standard HTTP methods (GET, POST, PUT, DELETE, etc.)

Each request is stateless.

Responses are uniform, predictable.

Aim: act on resources in a consistent, predictable way.

---

What Is Meant By "REST API Are Stateless" ?

Each request must contain everything needed to process it.

• The server keeps no session data about the client.

• No hidden "state" between calls.

---

What Is The Reason Of Making REST API Stateless ?

This makes REST scalable.

---

What are RESTful conventions ?

RESTful conventions = RESTful Endpoint conventions

RESTful conventions describe a predictable, resource-oriented way of designing HTTP APIs.

Everything is treated as a resource, and the HTTP method expresses the action.

Resource = Data → i.e. List Resources = Get All Items In A Collection

Overview

The convention combines: 1/ Base URL + 2/ Method + 3/ ID (optional)

1. Base URL (represents a collection) examples: /users, /products, /orders

2. Method examples: GET, POST, PUT, PATCH, DELETE

3. ID examples: 123, user120394

You might see the above described as:

• GET /, GET /:id, POST /, PUT /:id, DELETE /:id, etc

• the base URL is omitted bc implied, the pattern repeats itself no matter the collection targeted

---

Example Users Resource (Fully RESTful)

Method	Endpoint	Meaning
GET	/users	List all users
POST	/users	Create new user
GET	/users/123	Get user by ID
PUT	/users/123	Replace full user record
PATCH	/users/123	Update part of the user record
DELETE	/users/123	Delete user

---

Typical Implementation If Getting Many Resources From One Collection?

---

GET → GET /users → List all users

• Returns an array or paginated list.

• Should not modify anything (idempotent and safe).

---

Typical Implementation If Getting One Resource From One Collection?

GET /:id → GET /users/123 → Retrieve a single user

• Access an individual resource.

• Should be safe, meaning no side effects.

Example Response:

200 OK
{
  "id": 123,
  "name": "Alice",
  "email": "[e-mail]"
}

---

Typical Implementation If Creating A Resource In A Collection?

POST → i.e. POST /users → Create a new user

• POST is used on the collection URL.

• A new resource is created by sending JSON in the request body.

• The server generates a new ID.

• Returns 201 Created and often the created object or its URI.

Example Request:

POST /users
{
  "name": "Alice",
  "email": "[e-mail]"
}

---

Typical Implementation If Entirely Updating One Resource From One Collection?

PUT /:id → i.e. PUT /users/123 → Replace a resource

• Replaces the entire object, not a partial update.

• Should be idempotent (sending the same request multiple times yields the same state).

Example Request:

PUT /users/123
{
  "name": "Alice Smith",
  "email": "[e-mail]"
}

If you want partial updates, REST often uses PATCH instead of PUT.

---

Typical Implementation If Partially Updating One Resource From One Collection?

Partial updates implementation is optional but common.

PATCH /:id → i.e. PATCH /users/123 → Partially update a resource

• Only changes the fields provided.

• Not necessarily idempotent.

Example:

PATCH /users/123
{
  "email": "[e-mail]"
}

---

Typical Implementation If Deleting One Resource From One Collection?

DELETE /:id → DELETE /users/123 → Delete a resource

• Removes the resource permanently.

• Idempotent: deleting twice returns either 204 or 404.

---

Which Methods Are Idempotent?

GET, PUT, DELETE

Method	Idempotent?	Safe?	Typical Use
GET	Yes	Yes	Read
POST	No	No	Create
PUT	Yes	No	Replace / Full Update
PATCH	Not always	No	Partial Update
DELETE	Yes	No	Delete

Idempotent = Making the same request multiple times in a row has the same effect as making it once.

Safe = read-only operation = does not change the server’s state

---

What Are Some Additional Best Practices?

No trailing forward slash

/users ❌ /users/

Use hyphens

/user-preferences ❌ /userpreferences

Use hierarchical relationships

/user/cart-items

Use plural nouns

/users
/products
/orders

Use nouns, not verbs

❌ /getUser ❌ /createUser ✔️ /users/123 (GET retrieves, POST creates)

Use query parameters for filtering/pagination

GET /users?page=2&pageSize=20
GET /products?category=phones&sort=price

Return proper HTTP status codes

• 200 OK

• 201 Created

• 400 Bad Request

• 401 Unauthorized

• 404 Not Found

• 409 Conflict (e.g., duplicate email)

• 500 Internal Server Error

---

Difference Between Base URL vs Endpoint ?

The base URL is the root path for a resource collection - i.e. /users, /products, /orders

An endpoint is any specific path + method combination that the API exposes. Examples:

GET /users          ← endpoint
POST /users         ← endpoint
GET /users/123      ← endpoint
PUT /users/123      ← endpoint
DELETE /users/123   ← endpoint

---

What Is Meant By "PATCH Implementation Is Optional But Common" ?

PATCH is optional because not all APIs choose to support partial updates as a separate operation. Different API designs handle updates differently.

PATCH is the official HTTP method for partial updates (Strict REST), but some APIs choose alternatives:

1. Some APIs allow only full updates (using PUT), and no partial updates at all

2. Some APIs support partial updates, but not using PATCH - i.e. using POST

Scenario	Full update	Partial update	Common?	“RESTful”?
A. PUT only	PUT	❌ No partial updates	Yes	Yes
B. POST for updates	POST	POST	Yes (legacy/mixed)	Not strict REST
C. PUT + PATCH	PUT	PATCH	Most modern APIs	Most RESTful

---

What is meant by "The URL identifies the resource, not the action" ?

REST avoids verbs in URLs.

❌ /createUser ❌ /deleteOrder

✔️ /users ✔️ /orders/55

The HTTP method expresses the action.

---

What is meant by "Standard HTTP methods have meaning" ?

REST uses the semantics of HTTP instead of inventing new operations.

Method	Meaning	Example
GET	Read	GET /users
POST	Create	POST /users
PUT	Replace	PUT /users/123
PATCH	Partial update	PATCH /users/123
DELETE	Remove	DELETE /users/123

---

What Is Meant By "Uniform, predictable responses" ?

Clients should know what to expect:

• Standard status codes (200, 201, 404, 400, etc.)

• Standard error formats

• Standard representation types (usually JSON)

---

What Are The Categories Of HTTP Response Codes ?

5 classes:

Class	Meaning
1xx	Informational — rarely used
2xx	Success — the request succeeded
3xx	Redirect — client should go somewhere else
4xx	Client error — the request is wrong
5xx	Server error — the server failed

---

Can You Match Common REST API Endpoints To HTTP Response Codes ?

Endpoint	Method	Typical Success	Typical Errors
/users	GET	200	400, 401
/users	POST	201	400, 401, 409, 422
/users/:id	GET	200	401, 403, 404
/users/:id	PUT	200 / 204	400, 401, 403, 404, 409, 422
/users/:id	PATCH	200 / 204	400, 401, 403, 404, 409, 422
/users/:id	DELETE	204	401, 403, 404

In details:

Endpoint	Method	Success Codes	Common Error Codes
/users	GET	200 OK, 204 No Content	400 Bad Request, 401 Unauthorized
/users	POST	201 Created	400 Bad Request, 401 Unauthorized, 403 Forbidden, 409 Conflict, 422 Unprocessable Entity
/users/:id	GET	200 OK	400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
/users/:id	PUT	200 OK, 204 No Content	400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity
/users/:id	PATCH	200 OK, 204 No Content	400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity
/users/:id	DELETE	204 No Content	400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found

---

Can You Match HTTP Response Codes To Common REST API Endpoints?

Code	Name	When Used (REST)
200 OK	Success	GET, PUT, PATCH
201 Created	Resource created	POST
202 Accepted	Accepted, async processing	async jobs
204 No Content	Success, no body	PUT, PATCH, DELETE
301 Moved Permanently	Permanent redirect	rare in APIs
302 Found	Temporary redirect	rare in APIs
304 Not Modified	Cached resource unchanged	GET with ETag
400 Bad Request	Invalid request	wrong format, missing fields
401 Unauthorized	Not authenticated	JWT missing/invalid
403 Forbidden	Authenticated but not allowed	permissions
404 Not Found	Resource does not exist	ID not found
409 Conflict	Data conflict	duplicate email, versioning
422 Unprocessable Entity	Validation failed	semantic errors
429 Too Many Requests	Rate limit hit	throttling
500 Internal Server Error	Server crashed	unknown failure
502 Bad Gateway	Upstream error	microservices
503 Service Unavailable	Server down/overloaded	maintenance
504 Gateway Timeout	Upstream timeout	slow microservice

---

Architecture

---

Typical Architectures

1. Layered Architecture: folders config, loaders, apo, services, repositories, models, etc

2. Domain-Driven (DDD) Architecture: folders shared, users, products, auth, etc

---

Layered Architecture

Recommended for Most Projects

A clean separation of concerns improves maintainability, testability, and scalability.

src/
 ├── config/
 ├── loaders/          → startup logic (db, queues, cron)
 ├── api/
 │    ├── routes/
 │    ├── controllers/
 │    ├── validators/
 │    ├── middlewares/
 ├── services/
 ├── repositories/      → DB access layer
 ├── models/            → ORM/Schema definitions
 ├── utils/
 ├── app.js
 └── server.js

---

Why Use a Layered Architecture ?

• Separation of concerns

• Easy testing (mock services, mock repositories)

• Code remains clean as project grows

---

Layered Architecture: config/ directory

Centralized configuration using environment variables:

config/
 ├── env.js
 ├── database.js
 ├── logger.js

Use dotenv or dotenv-flow + a typed config validator (e.g., zod, joi).

---

Layered Architecture: loaders/ directory

Keeps startup logic organized:

loaders/
 ├── express.js
 ├── mongoose.js
 ├── redis.js
 └── events.js

Your server.js becomes clean:

import expressLoader from './loaders/express.js';
import dbLoader from './loaders/mongoose.js';

(async () => {
  await dbLoader();
  const app = await expressLoader();
})();

---

Layered Architecture: api/routes/ directory

Organize routes by domain (modular):

routes/
 ├── user.routes.js
 ├── auth.routes.js
 └── product.routes.js

---

Layered Architecture: api/controllers/ directory

Thin controllers — no business logic:

export const createUser = async (req, res, next) => {
  const user = await userService.createUser(req.body);
  res.status(201).json(user);
};

---

Layered Architecture: services/ directory

Contains business logic (independent of HTTP):

export const createUser = async (payload) => {
  const existing = await userRepo.findByEmail(payload.email);
  if (existing) throw new ConflictError("Email already exists");

  return userRepo.create(payload);
};

---

Layered Architecture: repositories/ directory

Data Access Layer - layer between services and database:

export const findByEmail = (email) => UserModel.findOne({ email });

Keeps services DB-agnostic (MongoDB → PostgreSQL becomes easier).

---

Layered Architecture: models/

Database models (Mongoose, Prisma, Sequelize, etc.).

---

Layered Architecture: middlewares/

Generic HTTP pipeline logic:

• Authentication

• Authorization

• Rate limiting

• Logging

• Error handler

Error handler example:

export function errorHandler(err, req, res, next) {
  console.error(err);
  res.status(err.status || 500).json({ message: err.message });
}

---

Domain-Driven (DDD) Architecture

Use if your API will grow large or is enterprise-level.

src/
 ├── modules/
 │    ├── user/
 │    │    ├── user.controller.js
 │    │    ├── user.service.js
 │    │    ├── user.repository.js
 │    │    ├── user.model.js
 │    │    └── user.routes.js
 │    └── auth/
 │         ├── auth.controller.js
 │         ├── auth.service.js
 │         ├── auth.routes.js
 ├── shared/
 └── server.js

• Highly modular

• Each domain is self-contained

• Best for microservices/multi-team projects

---

---

Methodologies To Build REST APIs

---

Intro

This is NOT abt the implementation details, but the how to approach the work (process, methodology, principles).

---

1. Test-Driven Development (TDD)

You already mentioned this. TDD focuses on:

• Write failing test → write minimal code → refactor

• Ensures contract clarity before implementation

• Encourages small, coherent components

• Prevents regression

For APIs, this usually means writing tests around:

• Endpoints

• Validation

• Auth flows

• Error responses

---

2. API-First (Design-First) Development

This is one of the most widely recommended methodologies for REST APIs.

Process:

1. Design your API contract first (OpenAPI/Swagger).

2. Get stakeholders aligned (backend, frontend, QA).

3. Generate stubs or mock servers.

4. Then implement the backend.

Benefits

• Shared language for developers

• Upfront thinking about resources, structure, naming

• Faster iteration because front-end can develop in parallel

• Prevents breaking changes later

Tools

• Swagger/OpenAPI

• Postman Collections

• Stoplight

• Apiary

---

3. Domain-Driven Design (DDD)

Not REST-specific, but widely used when building complex APIs.

Use DDD if:

• You have a large domain

• Many interacting entities

• Long-term complexity to manage

Focuses on:

• Ubiquitous language

• Aggregate roots

• Bounded contexts

• Modeling your API resources around domain concepts

Why it matters for REST:

• REST resources = often close to DDD aggregates

• Leads to clearer, stable endpoints

---

4. Iterative / Incremental API Evolution (Agile API development)

Build endpoints in small vertical slices:

1. Identify a user scenario

2. Define the minimal endpoints supporting it

3. Release early

4. Monitor usage

5. Evolve API without breaking changes

Often paired with:

• Feature flags

• Versioning strategies

• Changelogs

---

5. Consumer-Driven Contracts (CDC)

Very popular in microservice architecture.

Idea: Consumers define expectations on provider APIs, and provider tests against these expectations.

Tools:

• Pact

• Spring Cloud Contract

Benefits:

• Avoids breaking changes

• Forces clarity on what the consumer needs

• Enables independent deployments

---

6. Behavior-Driven Development (BDD)

Similar to TDD but focuses on business language.

Write tests like:

Given I am an authenticated user
When I GET /orders
Then I should receive a list of my orders

Tools:

• Cucumber

• Gherkin

Good when:

• Product managers and QA collaborate

• Requirements need to stay readable

---

🔧 Best Practices (Method-Level Principles)

These are not implementation details but concepts guiding how to build a good REST API.

---

2. Consistency over cleverness

Pick conventions early and enforce them:

• Naming

• Pagination

• Filtering

• Error format

• Authentication shape

Use linters or style guides:

• OpenAPI linter (Spectral)

• API style guide (GitHub, Stripe, Google guidelines)

---

3. Design for backward compatibility

Methodological principle:

Avoid breaking changes; evolve safely.

Use:

• Additive changes only

• Explicit versioning (/v1/...)

• Deprecation notices

---

4. Make error handling explicit

Define errors upfront:

• Error structure

• Error codes

• HTTP status mapping

Don’t improvise errors as you go.

---

5. Document continuously

Don’t treat documentation as a last step. Good APIs:

• Are self-documenting (OpenAPI)

• Have auto-updated docs (Swagger UI)

• Include examples

Documentation should evolve with the API, not after.

---

6. Validate input at the boundary

Methodology:

Validation is part of your API contract.

Define validation rules in the API specification first.

---

7. Think about observability early

Don’t wait until production.

Plan early for:

• Logs

• Structured error reports

• Metrics

• Tracing (OpenTelemetry)

---

8. Security from the start (Shift-left security)

Do not bolt on later.

Security-first processes:

• Threat modeling

• Consistent auth flow (OAuth2 / JWT etc.)

• API gateway rules

• Rate limits

• Secrets handling

---

🌟 Famous Guiding Principles

These are classic references when deciding how to build APIs:

1. Richardson Maturity Model (RMM)

Levels of API “RESTfulness”

• Level 0: RPC

• Level 1: Resources

• Level 2: HTTP verbs

• Level 3: HATEOAS (optional)

Helps you evaluate coherence, not design details.

---

2. REST Constraints (Roy Fielding)

Conceptual rules for REST method:

• Statelessness

• Uniform interface

• Cacheability

• Layered system

Useful for setting architectural mindset.

---

3. 12-Factor App Principles (for service side)

Not API-specific, but shapes how you build and deploy:

• Config in environment

• Dev/prod parity

• Logs as event streams

---

4. OpenAPI Guidelines (e.g., Microsoft/Google)

Blueprints for API methodology:

• Consistent naming

• Semantic versioning

• Pagination patterns

---

📌 Summary: Methodologies for Building REST APIs

Category	Methodologies
Testing-first	TDD, BDD, CDC
Design-first	API-First, OpenAPI-first
Architecture-first	DDD, RMM, REST constraints
Process-first	Agile slices, continuous documentation, shift-left security

---

More

---

1. ARCHITECTURE & CODE QUALITY

• Proper layered architecture (services, controllers, routes, etc)

• Request validation middleware using zod

• Global error handling middleware

• Custom error classes (ValidationError, DatabaseError, etc.)

• Standardized API response format

• Dependency injection pattern

2. DATABASE

• Database schema doesn't match frontend TypeScript types - must align before implementing CRUD

• Database seeding strategy (separate from migrations)

• Transaction handling for complex operations (bookings)

• ORM/query builder consideration (Prisma) for type safety

• Soft vs hard delete policy

3. API DESIGN

• Pagination for list endpoints

• Filtering & sorting query parameters

• Rate limiting middleware (express-rate-limit)

• API versioning strategy (/api/v1/...)

• Search functionality with complex filters

4. BUSINESS LOGIC

• Bookings CRUD endpoints (separate from Trips/Users)

• Booking constraints (seat availability, can't book own trip)

• Trip cancellation logic

• User rating calculations after trips

• Notification system (email/SMS for bookings)

5. TESTING

• Unit tests for services/repositories

• Integration tests for API endpoints

• Test database setup & teardown

• E2E API contract testing

• Minimum coverage thresholds

6. DEVOPS & DEPLOYMENT

• CI/CD pipeline setup

• Environment configuration validation

• Process management (PM2) for production

• Database migration strategy for production

---

Misc Best Practices

---

HTTPS

---

API Versioning

/api/v1/users
/api/v2/users

---

Use DTOs + Validation

Example with zod, joi, or yup:

const CreateUserSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

---

Follow 12-Factor App Principles

• .env for secrets (never commit them)

• Stateless services

• Logs to stdout

---

Logging & Monitoring

Use:

• Winston / Pino for logs

• Prometheus + Grafana or OpenTelemetry for metrics

---

Security Best Practices

• Helmet

• Rate-limiting

• Avoid exposing stack traces in production

• Sanitize input (MongoDB injection, etc.)

---

Use CI/CD + Automated Tests

Testing strategy:

• Unit tests → services, utilities

• Integration tests → controllers/routes

• E2E tests → full API test using Supertest

---

Use Frameworks When Helpful

For large projects:

✔ NestJS → already implements clean architecture, DI, modules, pipes, guards

For lightweight REST APIs:

✔ Express + Layered Architecture ✔ Fastify (faster & structured)

---

TODO

• How to use Swagger to design a REST API ?

• Postman vs Swagger

• Richardson Maturity Models -> level 2 is strict REST ?

• “Pure REST” (HATEOAS) vs practical REST

• A "REST API development checklist"

• OpenAPI/Swagger documentation

• REST best practices

• Recommended style guides on "how To Build REST APIs"

• Example step-by-step workflow using Methodologies To Build REST APIs

• Example REST API design for your project

• REST vs GraphQL

• REST vs gRPC

• Recommended books re "Methodologies To Build REST APIs"

• Testing REST APIs