diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml index ab80f55..b7555ce 100644 --- a/.github/workflows/docs-quality.yml +++ b/.github/workflows/docs-quality.yml @@ -44,7 +44,7 @@ jobs: run: | MISSING_LEVELS="" - for dir in CSS DOCKER GIT HTML JAVA JS NETWORKING SQL UX_UI_ACCESSIBILITY "IONIC+ANGULAR+FIREBASE+CAPACITOR" "REACT+SPRINGBOOT" ARCHITECTURE_AND_BEST_PRACTICES; do + for dir in CSS DOCKER GIT HTML JAVA JS NETWORKING API_AND_INTERFACE_DESIGN SQL UX_UI_ACCESSIBILITY "IONIC+ANGULAR+FIREBASE+CAPACITOR" "REACT+SPRINGBOOT" ARCHITECTURE_AND_BEST_PRACTICES; do if [ ! -d "$dir" ]; then continue fi diff --git a/API_AND_INTERFACE_DESIGN/01-API-Contracts-and-REST/README.md b/API_AND_INTERFACE_DESIGN/01-API-Contracts-and-REST/README.md new file mode 100644 index 0000000..25878bd --- /dev/null +++ b/API_AND_INTERFACE_DESIGN/01-API-Contracts-and-REST/README.md @@ -0,0 +1,156 @@ +# 01 β€” API Contracts and REST + +> **Why this matters:** if your contract is vague, teams integrate by guesswork. REST is the baseline style to learn because it forces clarity around resources, semantics, and errors. + +--- + +## 🎯 Problem + +Teams often ship endpoints quickly but forget contract quality: + +- inconsistent naming (`/getUsers`, `/users/list`, `/user`) +- success/error responses without predictable shape +- breaking changes without version strategy + +Result: fragile integrations, hidden coupling, and expensive migrations. + +--- + +## 🧠 Mental Model + +REST is **resource-oriented communication over HTTP semantics**. + +- Resource = business noun (`users`, `orders`, `invoices`) +- HTTP method = action semantics (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) +- Status code = outcome semantics (`2xx`, `4xx`, `5xx`) +- Representation = contract payload (usually JSON) + +If URL says noun, method says action, and response says outcome, the API is readable before opening the code. + +--- + +## πŸ”„ Flow (Request Lifecycle) + +```text +Client + β”œβ”€ 1) Sends HTTP request (method + URL + headers + optional body) + β”œβ”€ 2) Auth and validation run + β”œβ”€ 3) Business rule executes on resource + └─ 4) Server returns status + contract payload + metadata + +Contract guardrails: +- Correlation-Id for tracing +- Idempotency-Key where retries may duplicate writes +- Standard error envelope +``` + +--- + +## πŸ§ͺ Minimal Example + +### Resource design + +| Goal | Contract | +|------|----------| +| List users | `GET /v1/users?limit=20&cursor=abc` | +| Read one user | `GET /v1/users/{id}` | +| Create user | `POST /v1/users` | +| Replace user | `PUT /v1/users/{id}` | +| Patch user | `PATCH /v1/users/{id}` | +| Delete user | `DELETE /v1/users/{id}` | + +### Response envelope example + +```json +{ + "data": { + "id": "usr_123", + "name": "Ana", + "email": "ana@example.com" + }, + "meta": { + "requestId": "req_8f2", + "version": "v1" + } +} +``` + +### Error envelope example + +```json +{ + "error": { + "code": "VALIDATION_FAILED", + "message": "email is invalid", + "details": [{ "field": "email", "issue": "format" }] + }, + "meta": { + "requestId": "req_8f3" + } +} +``` + +--- + +## βœ… Strengths + +| Strength | Why It Helps | +|----------|--------------| +| Ubiquity | Every platform/tool understands HTTP/JSON | +| Cache friendliness | GET semantics integrate naturally with HTTP caches/CDN | +| Simple debugging | Easy inspection with browser, curl, logs | +| Stable governance model | OpenAPI + versioning + status semantics are mature | + +--- + +## ⚠️ Weaknesses + +| Weakness | Impact | +|----------|--------| +| Overfetch/underfetch risk | Fixed payloads may not match each client need | +| Verb drift in URLs | Teams accidentally create RPC-in-REST | +| Inconsistent semantics | Different teams misuse status codes/error models | + +--- + +## 🚫 Common Mistakes + +| Mistake | Why It Breaks | Better Choice | +|---------|----------------|---------------| +| `POST /getUsers` style endpoints | Hides semantics, kills predictability | Resource nouns + HTTP verbs | +| Returning `200` for every outcome | Clients cannot branch correctly | Use 4xx/5xx for errors | +| No idempotency strategy on writes | Retries create duplicates | Support `Idempotency-Key` on sensitive creates | +| Versioning by chaos | Breaking changes hurt integrations | Explicit version policy (`/v1`, compatibility rules) | + +--- + +## 🧭 Use When / Avoid When + +| Decision | Guidance | +|----------|----------| +| **Use REST when** | You need broad interoperability, CRUD-oriented resources, clear HTTP semantics, and straightforward governance. | +| **Avoid REST alone when** | Clients need highly customized graphs, strict internal low-latency RPC, or always-on realtime channels. | + +--- + +## πŸ›‘οΈ Governance Essentials + +| Area | Rule of Thumb | +|------|---------------| +| Versioning | Prefer additive changes first; reserve major bumps for true contract breaks | +| Compatibility | Never remove/rename fields silently; deprecate with timeline | +| Idempotency | Mandatory for retryable create/pay/order flows | +| Observability | Correlation IDs, request logs, and error taxonomy are non-negotiable | +| Security | HTTPS, authn/authz boundaries, and least-privilege scopes | + +--- + +## πŸ”— Related Topics + +- Transport and protocol internals: [Networking](../../NETWORKING/README.md) +- Macro architecture tradeoffs: [System Design](../../ARCHITECTURE_AND_BEST_PRACTICES/03-System-Design/README.md) +- Implementation in Java stack: [Spring Boot API](../../REACT+SPRINGBOOT/02-Spring-Boot-API/README.md) + +--- + +[⬅️ Back to Parent](../README.md) | [➑️ Next: 02-Query-RPC-and-Realtime-APIs](../02-Query-RPC-and-Realtime-APIs/README.md) diff --git a/API_AND_INTERFACE_DESIGN/02-Query-RPC-and-Realtime-APIs/README.md b/API_AND_INTERFACE_DESIGN/02-Query-RPC-and-Realtime-APIs/README.md new file mode 100644 index 0000000..ee99ff6 --- /dev/null +++ b/API_AND_INTERFACE_DESIGN/02-Query-RPC-and-Realtime-APIs/README.md @@ -0,0 +1,242 @@ +# 02 β€” Query, RPC, and Realtime APIs + +> **Why this matters:** REST is a strong baseline, but not every problem is CRUD. This module teaches when GraphQL, gRPC, WebSocket, or WebRTC is the right toolβ€”and when it is not. + +--- + +## 🧭 Quick Decision Table + +| Need | Usually Best First Candidate | Why | +|------|------------------------------|-----| +| Client-specific data shapes | **GraphQL** | Consumer asks for exactly what it needs | +| Fast internal service calls | **gRPC** | Strong typed contracts and efficient binary transport | +| Bidirectional app-server realtime | **WebSocket** | Persistent full-duplex channel | +| Browser peer-to-peer low-latency media/data | **WebRTC** | Designed for direct realtime peer communication | + +--- + +## 1) GraphQL + +### Problem + +REST endpoints can overfetch or underfetch when different clients need different field combinations. + +### Mental Model + +GraphQL is a **typed query language over a graph schema**. Clients request shape; server resolves fields. + +### Flow + +```text +Client sends query/mutation + └─ GraphQL gateway validates schema + └─ Resolvers fetch from services/data sources + └─ Gateway returns exactly requested shape +``` + +### Minimal Example + +```graphql +query UserCard { + user(id: "usr_123") { + name + orders(limit: 2) { id total } + } +} +``` + +### Strengths + +- Precision payloads per client +- Strong schema introspection +- Powerful for multi-client products + +### Weaknesses + +- Resolver complexity and N+1 traps +- Caching and cost control need explicit governance + +### Common Mistakes + +- No query depth/complexity limits +- No DataLoader-like batching for N+1 +- Exposing internal topology as schema + +### Use / Avoid + +- **Use when:** many clients need different views over related entities. +- **Avoid when:** you only need simple CRUD and want minimal operational overhead. + +--- + +## 2) gRPC + +### Problem + +Internal service-to-service communication needs low latency, strict contracts, and codegen across teams. + +### Mental Model + +gRPC is **remote procedure calls over typed Protobuf contracts**. + +### Flow + +```text +Client SDK (generated from .proto) + └─ HTTP/2 transport + └─ Service method execution + └─ Typed response or typed error status +``` + +### Minimal Example + +```proto +service UserService { + rpc GetUser (GetUserRequest) returns (GetUserResponse); +} + +message GetUserRequest { string id = 1; } +message GetUserResponse { string id = 1; string name = 2; } +``` + +### Strengths + +- Fast binary serialization +- Contract-first, strongly typed +- Native streaming support + +### Weaknesses + +- Harder browser/native web direct usage +- Debugging less human-readable than JSON + +### Common Mistakes + +- Breaking field numbering in `.proto` +- Mixing public edge concerns into internal RPC contracts +- Weak observability/metadata propagation + +### Use / Avoid + +- **Use when:** internal microservices require strict contracts and performance. +- **Avoid when:** public API ecosystem expects plain HTTP/JSON interoperability. + +--- + +## 3) WebSocket + +### Problem + +Polling every few seconds for changing data is wasteful and slow for live UX. + +### Mental Model + +WebSocket is a **persistent bidirectional tunnel** between client and server. + +### Flow + +```text +Client connects (HTTP upgrade) + └─ Auth handshake accepted + └─ Both sides send/receive events over one socket + └─ Heartbeats + reconnect strategy keep channel healthy +``` + +### Minimal Example + +```json +{ "event": "price.updated", "symbol": "AAPL", "value": 201.44 } +``` + +### Strengths + +- Real-time push without polling +- Bidirectional communication for interactive apps + +### Weaknesses + +- Stateful connection management complexity +- Requires explicit backpressure and reconnect rules + +### Common Mistakes + +- No heartbeat/timeout policy +- Missing auth token rotation on long-lived sessions +- No event schema versioning + +### Use / Avoid + +- **Use when:** chat, live dashboards, collaborative tools, multiplayer interactions. +- **Avoid when:** simple request/response suffices and infra should stay stateless. + +--- + +## 4) WebRTC + +### Problem + +Realtime media (audio/video) through a central server can add high latency and cost. + +### Mental Model + +WebRTC enables **peer-to-peer realtime media/data**, with signaling + ICE to establish paths. + +### Flow + +```text +Peer A and Peer B exchange SDP/ICE via signaling server + └─ Connectivity checks (STUN/TURN) + └─ Direct or relayed media/data channel established +``` + +### Minimal Example (conceptual) + +| Step | Action | +|------|--------| +| 1 | Create offer on Peer A | +| 2 | Send offer to Peer B via signaling API | +| 3 | Peer B answers and both exchange ICE candidates | +| 4 | Media/data channel starts | + +### Strengths + +- Very low-latency peer communication +- Built for browser-native media workflows + +### Weaknesses + +- NAT/firewall traversal complexity +- Operational dependency on TURN for hard networks + +### Common Mistakes + +- Assuming direct P2P always succeeds +- Ignoring fallback capacity planning for TURN +- Treating signaling as an afterthought + +### Use / Avoid + +- **Use when:** video/audio calls, realtime peer collaboration, data channels with low latency goals. +- **Avoid when:** deterministic request/response APIs are all you need. + +--- + +## βš–οΈ Comparison Snapshot + +| Dimension | GraphQL | gRPC | WebSocket | WebRTC | +|-----------|---------|------|-----------|--------| +| Primary mode | Query/mutation | RPC/stream | Event channel | Peer media/data | +| Typical coupling | Schema to gateway | Service contract | Event protocol | Signaling + ICE contracts | +| Browser fit | High | Medium (via gateway/transcoding) | High | High | +| Operational complexity | Medium | Medium | Medium-High | High | + +--- + +## πŸ”— Related Topics + +- HTTP/TLS foundations: [Networking](../../NETWORKING/README.md) +- Service tradeoffs at system scale: [System Design](../../ARCHITECTURE_AND_BEST_PRACTICES/03-System-Design/README.md) + +--- + +[⬅️ Back to Parent](../README.md) | [⬅️ Previous: 01-API-Contracts-and-REST](../01-API-Contracts-and-REST/README.md) | [➑️ Next: 03-Integration-Governance-and-Legacy](../03-Integration-Governance-and-Legacy/README.md) diff --git a/API_AND_INTERFACE_DESIGN/03-Integration-Governance-and-Legacy/README.md b/API_AND_INTERFACE_DESIGN/03-Integration-Governance-and-Legacy/README.md new file mode 100644 index 0000000..6c7b36e --- /dev/null +++ b/API_AND_INTERFACE_DESIGN/03-Integration-Governance-and-Legacy/README.md @@ -0,0 +1,178 @@ +# 03 β€” Integration, Governance, and Legacy + +> **Why this matters:** the hardest API problems are rarely β€œhow to return JSON.” They are integration reliability, backward compatibility, and long-term contract governance. + +--- + +## 🧭 Quick Path + +1. Pick integration style for the boundary (event callback, enterprise contract, etc.). +2. Define reliability semantics first (retry, idempotency, deduplication, timeout). +3. Define evolution rules (versioning, compatibility, deprecation timeline). +4. Add observability and security controls before rollout. + +--- + +## 1) Webhooks + +### Problem + +System A needs to notify System B asynchronously when events happen, without B polling constantly. + +### Mental Model + +Webhook = **event callback contract** over HTTP. + +Producer sends event to consumer URL when event occurs. + +### Flow + +```text +Event occurs on Producer + └─ Producer signs payload + sends POST callback + └─ Consumer verifies signature + processes event + └─ Consumer returns 2xx; otherwise Producer retries +``` + +### Minimal Example + +```json +{ + "event": "invoice.paid", + "id": "evt_9001", + "occurredAt": "2026-05-12T20:15:00Z", + "data": { "invoiceId": "inv_123", "amount": 149.00 } +} +``` + +### Strengths + +- Asynchronous and scalable integration pattern +- Decouples producer timing from consumer polling cadence + +### Weaknesses + +- Delivery is often at-least-once (duplicates are possible) +- Consumer endpoint reliability becomes critical + +### Common Mistakes + +- No signature verification +- No idempotency key / dedup by event ID +- Retry policy without dead-letter handling + +### Use / Avoid + +- **Use when:** event notifications to external partners or internal bounded contexts. +- **Avoid when:** strict immediate response data is required in same user flow. + +--- + +## 2) SOAP + +### Problem + +Some enterprise ecosystems require strict formal contracts, advanced WS-* standards, and long-lived legacy interoperability. + +### Mental Model + +SOAP = **XML message protocol with WSDL-defined contract**. + +### Flow + +```text +Client reads WSDL + └─ Generates contract-aware client + └─ Sends SOAP envelope + └─ Service validates and returns SOAP response/fault +``` + +### Minimal Example (envelope skeleton) + +```xml + + ... + + + inv_123 + + + +``` + +### Strengths + +- Formal contract governance (WSDL/XSD) +- Mature support in legacy enterprise environments + +### Weaknesses + +- Verbose payloads and tooling overhead +- Slower onboarding for modern web teams + +### Common Mistakes + +- Assuming SOAP is β€œbad by default” instead of evaluating constraints +- Mixing SOAP and REST semantics in a single contract surface without clear boundary + +### Use / Avoid + +- **Use when:** enterprise/regulated partners require formal SOAP contracts. +- **Avoid when:** modern public web API simplicity and developer experience are top priority. + +--- + +## πŸ›‘οΈ Contract Governance Rules + +| Area | Rule | Why | +|------|------|-----| +| Versioning | Prefer additive non-breaking changes; major versions only for unavoidable breaks | Protect existing consumers | +| Compatibility | Never silently remove/rename contract fields | Reduces integration outages | +| Error semantics | Publish stable error codes and remediation hints | Faster client-side recovery | +| Idempotency | Required for retried writes/events | Prevents duplicates and double charges | +| Deprecation | Announce timeline + migration path + sunset date | Predictable transitions | + +--- + +## πŸ” Observability Checklist + +- [ ] Correlation/request IDs in every interaction +- [ ] Structured logs with contract version and consumer identity +- [ ] Delivery metrics (success %, retries, DLQ counts) +- [ ] Alerting for error spikes by endpoint/event type +- [ ] Trace links across producer/consumer boundaries + +Without this, debugging distributed contract failures becomes guesswork. + +--- + +## πŸ” Security Checklist + +- [ ] TLS everywhere (in transit encryption) +- [ ] Message signing/HMAC for webhooks +- [ ] AuthN/AuthZ scopes per consumer +- [ ] Replay protection (timestamp/nonce windows) +- [ ] Secret rotation and key expiration policy + +Security is part of the contract, not an implementation detail. + +--- + +## βš–οΈ Selection Guidance by Scenario + +| Scenario | Better Default | Reason | +|----------|----------------|--------| +| Partner needs payment/completion notifications | Webhooks | Async callback model fits event-driven boundaries | +| Regulated enterprise integration with contract tooling | SOAP | Formal WSDL/XSD and compliance-friendly patterns | +| Internal domain events with strong retries/idempotency | Webhooks (or event bus + callback edge) | Better decoupling than synchronous waits | + +--- + +## πŸ”— Related Topics + +- Distributed tradeoffs and resilience patterns: [System Design](../../ARCHITECTURE_AND_BEST_PRACTICES/03-System-Design/README.md) +- HTTP transport and security basics: [Networking](../../NETWORKING/README.md) + +--- + +[⬅️ Back to Parent](../README.md) | [⬅️ Previous: 02-Query-RPC-and-Realtime-APIs](../02-Query-RPC-and-Realtime-APIs/README.md) diff --git a/API_AND_INTERFACE_DESIGN/README.md b/API_AND_INTERFACE_DESIGN/README.md new file mode 100644 index 0000000..728160d --- /dev/null +++ b/API_AND_INTERFACE_DESIGN/README.md @@ -0,0 +1,87 @@ +# πŸ”Œ API and Interface Design + +APIs are not β€œjust endpoints.” They are **contracts between systems**: agreements about data shape, timing, errors, ownership, and change over time. + +This topic teaches how to choose and design API styles with engineering judgment, so you can avoid cargo-cult choices like β€œalways REST” or β€œjust use GraphQL everywhere.” + +--- + +## πŸ“Š Objective Table: API Interface Design + +| Aspect | Didactic Explanation | +|--------|----------------------| +| **What is it for?** | Designing clear contracts so different systems (frontend, backend, services, partners) can communicate safely and evolve without chaos. | +| **What are the benefits?** | Lower coupling, clearer ownership, predictable errors, safer versioning, and easier observability when incidents happen. | +| **When to use it?** | Every time two components communicate across a boundary: browser↔API, service↔service, platform↔third-party, or realtime channels. | +| **When NOT to over-engineer it?** | Tiny prototypes or single-process scripts. Start simple, then increase contract rigor when integration risk appears. | + +--- + +## 🧠 Mental Model: Contracts, Not Code + +Think of an API like a legal contract: + +- **Parties**: who talks to whom (client/server, producer/consumer, peer/peer) +- **Language**: schema and protocol (JSON/OpenAPI, GraphQL schema, Protobuf, XML/WSDL) +- **Timing**: sync request/response vs async events vs long-lived streams +- **Breach handling**: error semantics, retries, idempotency, timeouts +- **Amendments**: versioning, compatibility, deprecation windows + +If these pieces are undefined, integration breaks even if your code compiles. + +--- + +## 🧭 API Style Matrix (Quick Selection) + +| Style | Interaction Model | Contract Shape | Best Fit | Watch Out | +|-------|-------------------|----------------|----------|-----------| +| **REST** | Sync request/response | Resource + HTTP semantics + OpenAPI | CRUD-heavy business APIs, public APIs | Verb-like URLs, wrong status codes, breaking changes | +| **GraphQL** | Sync query/mutation (optional subscriptions) | Typed graph schema | Multiple clients with different data needs | N+1 queries, over-flexibility without governance | +| **gRPC** | Sync RPC + streaming | Protobuf service contract | Internal service-to-service with strict performance | Browser compatibility and debugging complexity | +| **WebSocket** | Full-duplex persistent channel | Message protocol you define | Live dashboards, chat, collaborative apps | Backpressure, reconnect strategy, auth rotation | +| **WebRTC** | Peer-to-peer realtime media/data | SDP + ICE + signaling contract | Low-latency audio/video/data between clients | NAT traversal, signaling complexity | +| **Webhooks** | Async callbacks (event push) | Event payload + signature contract | Cross-system notifications | Retry/idempotency failures, unverified signatures | +| **SOAP** | Structured message exchange | WSDL + XML schema | Legacy enterprise integrations with strict contracts | Verbose payloads, tooling overhead | + +--- + +## 🧱 Boundary Guide (Avoid Duplication) + +| Topic | Owns This | API Topic Owns This | +|-------|-----------|---------------------| +| **Networking** | TCP, TLS, DNS, HTTP transport fundamentals | API contract design and style selection built on top of HTTP/networking | +| **System Design** | Scale, distributed tradeoffs, CAP, reliability architecture | Interface-level contract choices and compatibility rules | +| **React + Spring Boot** | Implementation details (controllers, DTOs, fetch/client usage) | Why a contract style is chosen and how to govern it | +| **JavaScript Async/APIs** | Consuming APIs from the client side | Designing producer-side contracts and multi-system evolution | + +Use this topic for **interface strategy**. Link out for transport internals, platform code, and macro-architecture. + +--- + +## πŸ“š Learning Path + +| Module | Focus | What You Will Learn | +|--------|-------|---------------------| +| [01-API-Contracts-and-REST](./01-API-Contracts-and-REST/README.md) | Baseline contract thinking | Resource modeling, HTTP semantics, idempotency, versioning, OpenAPI, and REST mistakes | +| [02-Query-RPC-and-Realtime-APIs](./02-Query-RPC-and-Realtime-APIs/README.md) | Specialized interaction styles | GraphQL, gRPC, WebSocket, and WebRTC selection and tradeoffs | +| [03-Integration-Governance-and-Legacy](./03-Integration-Governance-and-Legacy/README.md) | Async integration and lifecycle governance | Webhooks, SOAP, compatibility, observability, security, and deprecation | + +> **Start here if you are new:** Begin with [01-API-Contracts-and-REST](./01-API-Contracts-and-REST/README.md). The other styles make more sense once the contract baseline is solid. + +--- + +## πŸ“š Technical Glossary + +- **API Contract:** Shared agreement about requests, responses, errors, and change rules. +- **Consumer-Driven Contract:** A test/spec approach where consumers define expectations providers must keep. +- **Idempotency:** Repeating the same request produces the same effect (critical for retries). +- **Schema Evolution:** Changing contracts without breaking existing consumers. +- **Backward Compatibility:** Old clients keep working after a new release. + +--- + +### πŸ”— Global Navigation + +[⬅️ Previous Topic: Networking](../NETWORKING/README.md) | [🏠 Master Index](../README.md) | [➑️ Next Topic: SQL](../SQL/README.md) +
+**[⬇️ Dive In: 01-API-Contracts-and-REST](./01-API-Contracts-and-REST/README.md)** diff --git a/ARCHITECTURE_AND_BEST_PRACTICES/03-System-Design/README.md b/ARCHITECTURE_AND_BEST_PRACTICES/03-System-Design/README.md index 45d4538..dc882fd 100644 --- a/ARCHITECTURE_AND_BEST_PRACTICES/03-System-Design/README.md +++ b/ARCHITECTURE_AND_BEST_PRACTICES/03-System-Design/README.md @@ -189,40 +189,15 @@ --- -## πŸ“ API Design Patterns +## πŸ“ Boundary: System Design vs API Design -### RESTful API Design +System Design owns **distributed tradeoffs** (latency, consistency, scaling, resilience, queueing, observability). -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ β”‚ -β”‚ COLLECTION PATTERN β”‚ -β”‚ β”‚ -β”‚ GET /users ← List all users (paginated) β”‚ -β”‚ POST /users ← Create user β”‚ -β”‚ GET /users/{id} ← Get single user β”‚ -β”‚ PUT /users/{id} ← Replace user β”‚ -β”‚ PATCH /users/{id} ← Update user (partial) β”‚ -β”‚ DELETE /users/{id} ← Delete user β”‚ -β”‚ β”‚ -β”‚ NESTED RESOURCES β”‚ -β”‚ β”‚ -β”‚ GET /users/{id}/orders ← All orders for user β”‚ -β”‚ POST /users/{id}/orders ← Create order for user β”‚ -β”‚ GET /users/{id}/orders/{orderId} ← Specific order β”‚ -β”‚ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` +Canonical API style/contract design (REST, GraphQL, gRPC, WebSocket, Webhooks, WebRTC, SOAP) is documented in: -### GraphQL vs REST +- [`../../API_AND_INTERFACE_DESIGN/README.md`](../../API_AND_INTERFACE_DESIGN/README.md) -| Aspect | REST | GraphQL | -|--------|------|---------| -| **Data fetching** | Multiple endpoints | Single query | -| **Over-fetching** | Returns all fields | Ask for what you need | -| **Under-fetching** | N+1 problem possible | Can request all in one | -| **Caching** | HTTP caching natural | Custom caching | -| **Learning curve** | Simpler | Steeper | +Use that topic for protocol-style selection and contract governance, then come back here to reason about system-level impact. --- diff --git a/JS/03-Async-and-APIs/README.md b/JS/03-Async-and-APIs/README.md index 97ddb8c..8e21b80 100644 --- a/JS/03-Async-and-APIs/README.md +++ b/JS/03-Async-and-APIs/README.md @@ -262,6 +262,8 @@ const [users, posts] = await Promise.all([ ## 5. Fetch API β€” The HTTP Client +> πŸ“Œ **Boundary:** This folder teaches API **consumption** from JavaScript (fetch, async flow, error handling). For API **interface/style design** decisions (REST vs GraphQL/gRPC/WebSocket/Webhooks/WebRTC/SOAP), see [`../../API_AND_INTERFACE_DESIGN/README.md`](../../API_AND_INTERFACE_DESIGN/README.md). + ### How Fetch Works ``` diff --git a/NETWORKING/01-Web-Protocols/README.md b/NETWORKING/01-Web-Protocols/README.md index e115023..3931402 100644 --- a/NETWORKING/01-Web-Protocols/README.md +++ b/NETWORKING/01-Web-Protocols/README.md @@ -123,11 +123,11 @@ Imagine you're at a restaurant: --- -## πŸ—οΈ REST: The API Design Standard +## πŸ—οΈ REST: Protocol-Level Preview ### What is REST? -REST (Representational State Transfer) is a **set of conventions** for designing APIs that are predictable and easy to use. +REST (Representational State Transfer) is a **set of conventions** for designing APIs that are predictable and easy to use. In this Networking folder we only keep the **HTTP/protocol-facing basics**. ### RESTful URL Design @@ -169,6 +169,8 @@ REST (Representational State Transfer) is a **set of conventions** for designing β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` +> πŸ“Œ **Boundary:** Deep REST contract design (idempotency, versioning strategy, error semantics, compatibility) and style comparison with GraphQL/gRPC/WebSocket/Webhooks/WebRTC/SOAP is maintained in [`../../API_AND_INTERFACE_DESIGN/README.md`](../../API_AND_INTERFACE_DESIGN/README.md). + --- ## πŸ“¦ Request/Response Anatomy diff --git a/NETWORKING/README.md b/NETWORKING/README.md index 189c2ff..d8a2543 100644 --- a/NETWORKING/README.md +++ b/NETWORKING/README.md @@ -18,20 +18,25 @@ Understanding Networking sets you apart from "code ninjas" and moves you toward ## 🧠 Best Practices and Key Concepts ### 1. HTTP Protocol and Status Codes + Every time you request a webpage or submit a form, the server responds with a number (Status). Mastering these codes saves you headaches: + - **`2xx` (e.g., 200 OK):** Everything went perfectly. - **`3xx` (e.g., 301 Redirect):** The resource moved to another location. - **`4xx` (e.g., 404 Not Found, 401 Unauthorized):** You (the client/frontend dev) messed up. You sent data incorrectly or requested something that doesn't exist. - **`5xx` (e.g., 500 Internal Server Error):** I (the Server/Backend) crashed and failed on my own. ### 2. Ports β€” The "Doors" of a Building + A server (IP) is like a physical building. Ports are the office doors. + - To send Email, you knock on door (port) `25`. - To browse an insecure website (HTTP), you enter through door `80`. - If the site is secure (HTTPS with the padlock), you enter through the secure door `443`. - *For architectural security: All doors you don't use should be blocked by a Guard (Firewall).* ### 3. Security and State: JWT (JSON Web Token) + HTTP connections have no "memory" (*Stateless*). Every time you click, the server forgets who you are. To fix this, we use JWT: a temporary credential your browser shows the server on each request to remind it: *"Hey, it's still me, still logged in!"* > **Didactic Tip:** If an interview asks about the difference between URI and URL, remember this: **URI** is the exact "full name" of a resource in the universe. **URL** gives you the name AND the address (how to get there by taxi) via the `https://` protocol. Every URL is a URI, but not vice versa. @@ -51,14 +56,24 @@ HTTP connections have no "memory" (*Stateless*). Every time you click, the serve | Module | Description | |--------|-------------| -| [🌐 Web Protocols](./01-Web-Protocols/README.md) | HTTP methods, status codes, REST, request/response anatomy | +| [🌐 Web Protocols](./01-Web-Protocols/README.md) | HTTP methods, status codes, and request/response anatomy (transport/protocol focus) | | [πŸšͺ Dev Ports and Environments](./02-Dev-Ports-and-Envs/README.md) | Common dev ports table, Docker environments, debugging | | [πŸ” Security and JWT](./03-Security-and-JWT/README.md) | JWT structure, flow, OAuth 2.0, security best practices | > **Start here if you're new:** Begin with [Web Protocols](./01-Web-Protocols/README.md) to understand the foundation, then explore [Dev Ports](./02-Dev-Ports-and-Envs/README.md) for practical development. --- + ### πŸ”— Global Navigation -[⬅️ Previous Topic: Docker](../DOCKER/README.md) | [🏠 Master Index](../README.md) | [➑️ Next Topic: SQL](../SQL/README.md) + +[⬅️ Previous Topic: Docker](../DOCKER/README.md) | [🏠 Master Index](../README.md) | [➑️ Next Topic: API and Interface Design](../API_AND_INTERFACE_DESIGN/README.md)
**[⬇️ Dive In: 01-Web-Protocols](./01-Web-Protocols/README.md)** + +--- + +## 🧭 Boundary Note: Networking vs API Design + +- This topic owns **transport and protocol foundations** (HTTP mechanics, ports, TLS, request/response transport). +- The canonical topic for **API contract and style design** (REST, GraphQL, gRPC, WebSocket, Webhooks, WebRTC, SOAP) lives in: + - [`../API_AND_INTERFACE_DESIGN/README.md`](../API_AND_INTERFACE_DESIGN/README.md) diff --git a/REACT+SPRINGBOOT/02-Spring-Boot-API/README.md b/REACT+SPRINGBOOT/02-Spring-Boot-API/README.md index 1c14398..ba00096 100644 --- a/REACT+SPRINGBOOT/02-Spring-Boot-API/README.md +++ b/REACT+SPRINGBOOT/02-Spring-Boot-API/README.md @@ -42,7 +42,7 @@ Spring Boot is a **Java framework** that makes building REST APIs effortless. It --- -## 🎯 REST API Design +## 🎯 API Endpoint Conventions (Implementation Scope) | What to do βœ… | What NOT to do ❌ | Why | |--------------|-------------------|-----| @@ -60,6 +60,8 @@ Spring Boot is a **Java framework** that makes building REST APIs effortless. It | `PUT` | Update entire resource | `PUT /pizzas/1` | | `DELETE` | Remove resource | `DELETE /pizzas/1` | +> πŸ“Œ **Boundary:** This chapter focuses on implementing endpoints in Spring Boot. For API contract theory and style selection (REST vs GraphQL/gRPC/WebSocket/Webhooks/WebRTC/SOAP), use [`../../API_AND_INTERFACE_DESIGN/README.md`](../../API_AND_INTERFACE_DESIGN/README.md). + --- ## πŸ” JWT Authentication Flow diff --git a/README.md b/README.md index 137f119..9283b33 100644 --- a/README.md +++ b/README.md @@ -76,6 +76,11 @@ ROOT (Master Index) β”‚ β”œβ”€β”€ 02-Dev-Ports-and-Envs β”‚ └── 03-Security-and-JWT β”‚ +β”œβ”€β”€ πŸ”Œ API_AND_INTERFACE_DESIGN +β”‚ β”œβ”€β”€ 01-API-Contracts-and-REST +β”‚ β”œβ”€β”€ 02-Query-RPC-and-Realtime-APIs +β”‚ └── 03-Integration-Governance-and-Legacy +β”‚ β”œβ”€β”€ 🐘 SQL β”‚ β”œβ”€β”€ 01-Relational-Design β”‚ β”œβ”€β”€ 02-Queries-and-Joins @@ -103,8 +108,9 @@ ROOT (Master Index) | 08 | πŸ™ **[Git](./GIT)** | Version control fundamentals, GitHub collaboration, pull requests, and CI/CD workflows. | [Dive in](./GIT/01-Git-Fundamentals/README.md) | | 09 | 🐳 **[Docker](./DOCKER)** | Images, containers, volumes, storage, and multi-service local environments. | [Dive in](./DOCKER/01-Images-and-Containers/README.md) | | 10 | 🌎 **[Networking](./NETWORKING)** | Web protocols, ports, environments, authentication flows, security, and JWT. | [Dive in](./NETWORKING/01-Web-Protocols/README.md) | -| 11 | 🐘 **[SQL](./SQL)** | Relational design, queries, joins, indexing, and performance fundamentals. | [Dive in](./SQL/01-Relational-Design/README.md) | -| 12 | 🎨 **[UX/UI Accessibility](./UX_UI_ACCESSIBILITY)** | Visual design rules, WCAG accessibility, and documentation that reduces cognitive load. | [Dive in](./UX_UI_ACCESSIBILITY/01-Visual-Design-Rules/README.md) | +| 11 | πŸ”Œ **[API and Interface Design](./API_AND_INTERFACE_DESIGN)** | API contracts, style selection (REST/GraphQL/gRPC/WebSocket/Webhooks/WebRTC/SOAP), and governance guidance. | [Dive in](./API_AND_INTERFACE_DESIGN/01-API-Contracts-and-REST/README.md) | +| 12 | 🐘 **[SQL](./SQL)** | Relational design, queries, joins, indexing, and performance fundamentals. | [Dive in](./SQL/01-Relational-Design/README.md) | +| 13 | 🎨 **[UX/UI Accessibility](./UX_UI_ACCESSIBILITY)** | Visual design rules, WCAG accessibility, and documentation that reduces cognitive load. | [Dive in](./UX_UI_ACCESSIBILITY/01-Visual-Design-Rules/README.md) | --- diff --git a/SQL/README.md b/SQL/README.md index 09d7b03..1127bce 100644 --- a/SQL/README.md +++ b/SQL/README.md @@ -48,7 +48,9 @@ Think of it as a massive, excellently organized office file cabinet, full of dra - **CRUD:** Acronym for **C**reate, **R**ead, **U**pdate, **D**elete. The four basic operations of any data system. --- + ### πŸ”— Global Navigation -[⬅️ Previous Topic: Networking](../NETWORKING/README.md) | [🏠 Master Index](../README.md) | [➑️ Next Topic: UX, UI & Accessibility](../UX_UI_ACCESSIBILITY/README.md) + +[⬅️ Previous Topic: API and Interface Design](../API_AND_INTERFACE_DESIGN/README.md) | [🏠 Master Index](../README.md) | [➑️ Next Topic: UX, UI & Accessibility](../UX_UI_ACCESSIBILITY/README.md)
**[⬇️ Dive In: 01-Relational-Design](./01-Relational-Design/README.md)**