Skip to content

Commit a33e6b7

Browse files
NeaByteLabNeaByteLab
committed
docs(deep-notes): add rest api note series 📕
- Add REST API note files for fundamentals, HTTP semantics, payload validation, status errors, and URI design - Add REST API series index file under DEEP-NOTES/Rest-API - Update Deep Notes catalog table to include the REST API series link
1 parent 0f93b84 commit a33e6b7

7 files changed

Lines changed: 540 additions & 0 deletions

File tree

‎DEEP-NOTES/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ _Structured learning notes: one topic per file, frontmatter and structured body.
66

77
| Series | Description | Link |
88
| ------------------- | -------------------------------------------------------------------------- | -------------------------------------- |
9+
| **REST API** | REST API foundations, HTTP semantics, URI design, status and validation. | [Rest-API/](./Rest-API/) |
910
| **Time Complexity** | Big O: O(1) → O(n!). Definition, analogy, when it shows up, code examples. | [Time-Complexity/](./Time-Complexity/) |
1011

1112
---

‎DEEP-NOTES/Rest-API/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# REST API Deep Notes
2+
3+
_One file per REST API concept. Structured, practical, reusable._
4+
5+
## Contents
6+
7+
| File | Topic | One-line |
8+
| ------------------------------------------------ | ------------------ | ------------------------------------------------------ |
9+
| [api-fundamentals.md](./api-fundamentals.md) | API Fundamentals | What REST API is, and what it is not |
10+
| [http-semantics.md](./http-semantics.md) | HTTP Semantics | Method meaning and idempotency basics |
11+
| [uri-design.md](./uri-design.md) | URI Design | Resource naming rules for consistent endpoints |
12+
| [status-errors.md](./status-errors.md) | Status Errors | Status code mapping and stable error contract |
13+
| [payload-validation.md](./payload-validation.md) | Payload Validation | Request and response validation for safe API contracts |

‎DEEP-NOTES/Rest-API/api-fundamentals.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
title: 'API Fundamentals'
3+
source: 'https://restfulapi.net/'
4+
description: 'Core REST API principles, constraints, and practical boundaries.'
5+
tags: ['rest-api', 'http', 'architecture']
6+
---
7+
8+
# API Fundamentals
9+
10+
## Overview
11+
12+
REST API is not just JSON over HTTP. It is a design style for exposing resources through clear
13+
interfaces. Good REST design makes contracts predictable, easier to evolve, and easier to debug.
14+
15+
The main goal is consistency. Teams move faster when naming, behavior, and response shape are
16+
stable across endpoints.
17+
18+
### Quick Takeaways
19+
20+
- Design resource-first, not action-first
21+
- Keep contracts stable across endpoints
22+
- Use HTTP semantics as interface guarantees
23+
24+
## Definition
25+
26+
REST is an architectural style where:
27+
28+
- resources are identified by URIs
29+
- operations use standard HTTP methods
30+
- communication is stateless
31+
- responses are cache-aware when possible
32+
33+
## The Analogy
34+
35+
Think of REST API like a well-organized library:
36+
37+
- URI is the shelf location
38+
- method is the action (read, add, update, remove)
39+
- status code is the librarian response
40+
- payload is the actual book content
41+
42+
If every shelf uses different rules, nobody finds anything.
43+
44+
## When You See It
45+
46+
You are usually in REST territory when:
47+
48+
- your backend exposes CRUD-like resources
49+
- multiple clients need the same contract
50+
- you need long-term maintainability and observability
51+
52+
## Examples
53+
54+
**Good:**
55+
56+
- `GET /v1/prompts`
57+
- `POST /v1/prompts`
58+
- `PATCH /v1/prompts/{id}`
59+
60+
**Bad:**
61+
62+
- `POST /getPromptsList`
63+
- `POST /deletePromptById`
64+
- `POST /editPrompt`
65+
66+
**Good snippet (uniform contract):**
67+
68+
```http
69+
GET /v1/prompts
70+
POST /v1/prompts
71+
PATCH /v1/prompts/{id}
72+
DELETE /v1/prompts/{id}
73+
```
74+
75+
**Bad snippet (action endpoints):**
76+
77+
```http
78+
POST /v1/getPromptsList
79+
POST /v1/removePromptById
80+
POST /v1/updatePromptById
81+
```
82+
83+
## Important Points
84+
85+
- Resource-first design beats action-first URL naming
86+
- Stateless requests simplify scaling and retries
87+
- Uniform conventions reduce client complexity
88+
- REST is a style, not a strict spec
89+
90+
## Summary
91+
92+
- REST API is about predictable contracts, not trends.
93+
- Stable structure now prevents expensive rewrites later.
94+
- _Consistency is the real speed multiplier in API systems._

‎DEEP-NOTES/Rest-API/http-semantics.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
title: 'HTTP Semantics'
3+
source: 'https://www.rfc-editor.org/rfc/rfc9110'
4+
description: 'How HTTP methods express intent, safety, and idempotency in REST APIs.'
5+
tags: ['rest-api', 'http-methods', 'semantics']
6+
---
7+
8+
# HTTP Semantics
9+
10+
## Overview
11+
12+
HTTP methods are contracts. If method semantics are wrong, clients cannot trust your API behavior.
13+
Most production API bugs start from semantic mismatch, not syntax errors.
14+
15+
This note focuses on method intent, safety, and idempotency.
16+
17+
### Quick Takeaways
18+
19+
- Method choice defines behavior expectations
20+
- Do not use `GET` for state changes
21+
- Idempotency is critical for retry-safe operations
22+
23+
## Definition
24+
25+
- **Safe methods:** do not change server state (`GET`, `HEAD`)
26+
- **Idempotent methods:** repeated call has same final state (`PUT`, `DELETE`)
27+
- **Non-idempotent methods:** repeated call may create different outcomes (`POST`)
28+
29+
### Method Matrix
30+
31+
- `GET`: safe yes, idempotent yes, common use is read resource
32+
- `POST`: safe no, idempotent no, common use is create action/session/resource
33+
- `PUT`: safe no, idempotent yes, common use is full replace intent
34+
- `PATCH`: safe no, usually non-idempotent, common use is partial update
35+
- `DELETE`: safe no, idempotent yes, common use is remove resource
36+
37+
## The Analogy
38+
39+
Pressing an elevator button:
40+
41+
- `GET`: check current floor display
42+
- `POST`: call elevator for a new trip
43+
- `PUT`: set floor indicator to a specific value
44+
- `DELETE`: clear a scheduled stop
45+
46+
Pressing once or five times should follow method semantics.
47+
48+
## When You See It
49+
50+
Common API design decisions:
51+
52+
- create session or token -> `POST`
53+
- update one field -> `PATCH`
54+
- replace full resource -> `PUT`
55+
- remove resource -> `DELETE`
56+
57+
## Examples
58+
59+
**Good:**
60+
61+
- `DELETE /v1/sessions/{id}` to revoke one session
62+
63+
**Bad:**
64+
65+
- `GET /v1/logout` that mutates session state
66+
67+
**Good snippet (Express style):**
68+
69+
```ts
70+
app.put('/v1/users/:id', async (req, res) => {
71+
const user = await replaceUser(req.params.id, req.body)
72+
return res.status(200).json(user)
73+
})
74+
75+
app.patch('/v1/users/:id', async (req, res) => {
76+
const user = await updateUserPartial(req.params.id, req.body)
77+
return res.status(200).json(user)
78+
})
79+
```
80+
81+
**Bad snippet (semantic mismatch):**
82+
83+
```ts
84+
app.get('/v1/logout', async (_req, res) => {
85+
await revokeSession()
86+
return res.status(200).json({ ok: true })
87+
})
88+
```
89+
90+
## Important Points
91+
92+
- Use method semantics as interface guarantees
93+
- Do not hide mutations behind `GET`
94+
- Idempotency helps retries under network failure
95+
- `PATCH` is partial update, `PUT` is full replacement intent
96+
97+
## Common Mistakes
98+
99+
- Using `POST` for every endpoint because it feels easier
100+
- Treating `PATCH` as full replace and silently dropping omitted fields
101+
- Returning different behavior for the same method on similar resources
102+
103+
## Summary
104+
105+
- Method choice is behavior design, not naming preference.
106+
- Correct semantics reduce hidden production risk.
107+
- _If clients must guess behavior, semantics are already broken._

‎DEEP-NOTES/Rest-API/payload-validation.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: 'Payload Validation'
3+
source: 'https://json-schema.org/understanding-json-schema/'
4+
description: 'Request and response validation patterns to protect API contracts and data quality.'
5+
tags: ['rest-api', 'validation', 'api-contract']
6+
---
7+
8+
# Payload Validation
9+
10+
## Overview
11+
12+
Validation protects system boundaries. Without strict validation, bad payloads leak into storage,
13+
business logic, and downstream services.
14+
15+
Validation should happen before business processing starts.
16+
17+
### Quick Takeaways
18+
19+
- Validate payloads at API boundaries
20+
- Use explicit schema-based checks
21+
- Return structured field-level validation errors
22+
23+
## Definition
24+
25+
Payload validation checks:
26+
27+
- shape (required fields, types)
28+
- constraints (length, range, enum)
29+
- semantic consistency (cross-field logic)
30+
- request and response payload contracts
31+
32+
## The Analogy
33+
34+
Airport security screening:
35+
36+
- identity check -> required fields
37+
- bag scan -> type and constraint checks
38+
- additional checks -> semantic rules
39+
40+
Skipping one checkpoint increases risk downstream.
41+
42+
## When You See It
43+
44+
You need strong validation in:
45+
46+
- create and update endpoints
47+
- webhook receivers
48+
- public APIs with untrusted clients
49+
- internal APIs with multiple teams
50+
51+
## Examples
52+
53+
**Good:**
54+
55+
- Reject invalid payload with `422` and field-level errors
56+
57+
**Bad:**
58+
59+
- Accept everything, fail later in DB with generic `500`
60+
61+
**Good snippet (schema first):**
62+
63+
```ts
64+
const result = createPromptSchema.safeParse(req.body)
65+
if (!result.success) {
66+
return res.status(422).json({
67+
code: 'validation_failed',
68+
details: result.error.issues
69+
})
70+
}
71+
```
72+
73+
**Bad snippet (late failure):**
74+
75+
```ts
76+
try {
77+
await db.prompts.insert(req.body)
78+
return res.status(201).json({ ok: true })
79+
} catch {
80+
return res.status(500).json({ message: 'Something went wrong' })
81+
}
82+
```
83+
84+
## Important Points
85+
86+
- Validate at API boundary, not deep in service chain
87+
- Use explicit schemas, not ad-hoc checks
88+
- Return structured errors for each invalid field
89+
- Validate responses for critical public endpoints
90+
91+
## Status Code Boundary
92+
93+
- Use `400` when request syntax is malformed
94+
- Use `422` when syntax is valid but business payload is invalid
95+
- Use `500` only for unexpected server-side failures
96+
97+
## Summary
98+
99+
- Validation preserves contract quality and operational stability.
100+
- Early rejection is cheaper than late failure.
101+
- _Strict boundaries keep systems flexible, not rigid._

0 commit comments

Comments
 (0)