Bài 61: CRUD HTTP Endpoint Overview — Resource Modeling

Sau bài học, bạn sẽ:

• Hiểu REST resource modeling: noun-based URL, hierarchy, action vs resource.
• Phân biệt idempotency vs safe method: GET/HEAD safe, PUT/DELETE idempotent, POST không.
• Áp dụng ETag header + If-None-Match cho conditional GET (cache).
• Hiểu PUT vs PATCH semantic và áp dụng đúng cho Shop API.
• Phân biệt offset pagination vs cursor pagination — trade-off và use case.
• Versioning strategy: URL path (/v1) vs header (Accept: application/vnd.shop.v1+json).
• Nắm roadmap Group 7 (B61-B75): full CRUD pattern cho 6 resource Shop API.

Nguyên tắc cốt lõi REST: resource (tài nguyên) là danh từ — vật được tham chiếu, không phải hành động. HTTP method là động từ tác động lên resource đó.

• URL đúng REST: /products, /orders, /users (đều là danh từ số nhiều).
• URL sai (verb trong URL): /getProducts, /createOrder, /listAllUsers — đây là kiểu RPC trá hình REST, mất khả năng tận dụng HTTP method semantic và cache layer.

Phân loại URL chuẩn theo Fielding Dissertation 2000 và pattern industry (GitHub API, Stripe API):

• Collection — tập hợp resource, dùng dạng số nhiều: /products.
• Item — instance cụ thể, gắn identifier: /products/{slug} (Shop API dùng slug cho human-friendly URL).
• Sub-resource — resource thuộc về resource cha: /users/{id}/orders (đơn hàng của user cụ thể).

URL structure Shop API lock vĩnh viễn cho 6 resource chính:

/api/v1/products              GET list, POST create
/api/v1/products/{slug}       GET, PATCH, DELETE
/api/v1/orders                GET list, POST create
/api/v1/orders/{id}           GET, PATCH (limited: cancel)
/api/v1/orders/{id}/cancel    POST  (action verb non-CRUD)
/api/v1/users/me              GET self
/api/v1/users/{id}/orders     GET orders của user
/api/v1/cart                  GET, POST add item, DELETE clear
/api/v1/cart/items/{id}       PATCH qty, DELETE remove
/api/v1/categories            GET tree, POST create (admin)

Hierarchy depth max 2 level. URL kiểu /users/{id}/orders/{order_id}/items/{item_id}/reviews đẩy người đọc và route table vào nightmare. Khi nested cần sâu hơn 2, flatten về root: /orders/{id} truy cập trực tiếp đơn hàng theo ID, không cần biết owner.

Action verb cho non-CRUD endpoint. Có những thao tác không phải CRUD đơn thuần — chuyển state, kích hoạt job, trigger workflow. REST puristic muốn ép vào noun (kiểu POST /cancellations với body {"order_id": ...}), nhưng pattern industry chấp nhận action verb với POST:

POST /api/v1/orders/{id}/cancel    # state machine action
POST /api/v1/products/{slug}/restore   # admin un-delete
POST /api/v1/checkout                  # process workflow
POST /api/v1/payments/{id}/refund      # state machine action

Pattern lock cho Shop API: /<resource>/{id}/<action> với HTTP method POST (vì action thay đổi state, không idempotent theo nghĩa CRUD). GitHub API dùng cùng pattern (POST /repos/{owner}/{repo}/pulls/{number}/merge), Stripe cũng vậy (POST /v1/refunds nhưng cũng có dạng POST /v1/charges/{id}/capture).

HTTP method có 2 đặc tính độc lập theo RFC 9110 section 9.2.1 và 9.2.2:

• Safe — method chỉ đọc, không thay đổi state server (read-only). Client tự do retry, prefetch, hoặc gọi trước khi user click. Áp dụng: GET, HEAD, OPTIONS.
• Idempotent — gọi N lần (N ≥ 1) tạo ra cùng kết quả state với gọi đúng 1 lần. Client retry an toàn khi network timeout. Áp dụng: GET, HEAD, OPTIONS, PUT, DELETE.

Bảng tổng hợp:

Method | Safe | Idempotent | Mô tả
GET    | YES  | YES        | Read resource
HEAD   | YES  | YES        | Read metadata only (no body)
POST   | NO   | NO         | Create new (mỗi POST = 1 resource mới)
PUT    | NO   | YES        | Replace toàn bộ (PUT 2 lần = state cuối giống PUT 1 lần)
PATCH  | NO   | depends    | Partial update — idempotent KHI absolute value
DELETE | NO   | YES        | Delete (DELETE 2 lần — lần 2 trả 404 cũng OK)

PATCH idempotent tùy nội dung body:

• Idempotent KHI dùng absolute value: PATCH /products/iphone-15 {"stock": 5} — gọi 2 lần stock vẫn là 5.
• KHÔNG idempotent KHI dùng delta relative: PATCH /products/iphone-15 {"stock_delta": -1} — gọi 2 lần stock giảm 2 thay vì 1.

Lock decision Shop API: PATCH dùng absolute value, KHÔNG dùng delta. Lý do: client retry trên network timeout (3G/4G hay rớt, tower-http retry layer reattempt) phải an toàn — delta gọi 2 lần là bug nhân đôi.

Stock decrement trong order creation là use case ngoại lệ — nhưng phía server xử lý bên trong transaction (B54 create_order_atomic) chứ không expose qua PATCH endpoint cho client. Client không bao giờ gửi delta qua HTTP.

Idempotency-Key header — pattern Stripe-introduced để biến POST (vốn không idempotent) thành retry-safe:

POST /api/v1/orders HTTP/1.1
Host: shop.local
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{"items": [{"product_id": 1, "quantity": 2}]}

Cơ chế: server lưu key + response trong cache (Redis, TTL 24 giờ). Request lần 2 cùng key trả response cached cũ — không tạo order trùng. Áp dụng cho POST /orders và POST /payments (Shop API lock, deep B66) chính là cách Stripe và Square xử lý retry trên flaky network ([Stripe Idempotent Requests docs](https://stripe.com/docs/api/idempotent_requests)).

Idempotency-Key flow:
1. Client tạo UUID v4, gửi với POST /orders
2. Server check Redis: idem:<key>
   - Hit → trả response cũ, KHÔNG tạo order mới
   - Miss → xử lý bình thường, lưu (key, response) vào Redis TTL 24h
3. Network timeout → client retry cùng key → server trả response cũ

Bảng idempotency_keys đã có trong project spec (Group 1 plan) — phục vụ pattern này từ B66.

Cả 2 đều update resource, nhưng semantic khác hẳn:

• PUT — replace toàn bộ: client gửi full representation của resource, server lưu giống y client gửi. Field thiếu trong body → reset về default hoặc trả 422. Use case: import full resource, admin restore exact state, sync 2 chiều.
• PATCH — partial update: client gửi chỉ field cần update, server merge với current state trong DB. Field thiếu → giữ nguyên. Use case: user UI update vài field (đổi tên sản phẩm, đổi giá).

So sánh chi tiết:

Operation         | PUT                    | PATCH (B42 lock)
Body              | Full resource          | Partial fields only
Missing field     | Reset hoặc 422         | Giữ nguyên DB (no-op)
Null field        | Set NULL field         | Set NULL (Some(None) B42)
Idempotent        | YES                    | YES (absolute) / NO (delta)
Risk overwrite    | High (toàn bộ resource)| Low (chỉ field gửi)
Shop API decision | KHÔNG dùng             | DÙNG (B42 + B53 lock)

Lock decision Shop API:

• PATCH cho user-facing update 95% case — UI form admin/user gửi chỉ field thay đổi, server merge. Pattern đã implement B42 (UpdateProductDto double-Option Option<Option<T>>) và B53 (update_product với COALESCE cho NOT NULL + CASE WHEN $boolean cho nullable).
• PUT KHÔNG dùng — quá over-permissive cho REST API. Client UI vô tình quên field price khi gửi PUT → giá reset về 0, lỗi production silent. PATCH bảo vệ semantic merge.
• Exception: admin import/restore từ JSON backup có thể dùng PUT (rất hiếm, sẽ deep ở G14 admin endpoints).

Một ví dụ thực tế phân biệt: client muốn xóa description của sản phẩm (set NULL). Với PATCH, body {"description": null} hợp lệ — handler nhận Some(None) qua double-Option và set NULL trong DB. Với PUT, client phải gửi nguyên resource thiếu key description hoặc set null — semantic mơ hồ, dễ confuse.

Kết luận: PATCH là default cho Shop API. Không cần endpoint PUT trừ tính năng admin restore từ backup file (sẽ note khi xuất hiện, không trước).

Vấn đề: client cache resource sau lần GET đầu, nhưng vẫn phải gọi lại để check resource có đổi không. Mỗi request tốn bandwidth dù body không đổi. ETag (entity tag) là cơ chế HTTP-native giải quyết: server gửi tag identifier cho version hiện tại, client gửi lại tag khi GET lần sau, server check, nếu trùng trả 304 Not Modified không body — save bandwidth toàn bộ payload.

Flow theo RFC 9110 section 8.8.3:

# Request 1 — fresh fetch
GET /api/v1/products/iphone-15 HTTP/1.1
Host: shop.local

# Response 1
HTTP/1.1 200 OK
ETag: W/"1718438400"
Content-Type: application/json
Cache-Control: public, max-age=300

{"slug": "iphone-15", "name": "iPhone 15", "price": "25000000", ...}

# Request 2 — sau khi client cache, kèm ETag cũ
GET /api/v1/products/iphone-15 HTTP/1.1
Host: shop.local
If-None-Match: W/"1718438400"

# Response 2 — không thay đổi
HTTP/1.1 304 Not Modified
ETag: W/"1718438400"
(no body — save bandwidth toàn bộ JSON)

2 cách generate ETag:

• Strong ETag — hash content (SHA256 truncate 16 bytes hoặc tương đương). Chính xác nhưng tốn CPU mỗi response: phải serialize JSON, hash, so sánh.
• Weak ETag — prefix W/, thường là timestamp hoặc version counter: W/"<updated_at_unix>". Chấp nhận false negative rất ít (nếu update trong cùng giây cùng resource — gần như không gặp trong workload Shop API).

Lock decision Shop API:

• Weak ETag W/"<updated_at_unix>" — dùng cột updated_at đã có sẵn ở mọi entity (B51 schema lock), convert sang Unix timestamp.
• Áp dụng cho GET single resource (item endpoint) — GET /api/v1/products/{slug}, GET /api/v1/orders/{id}, GET /api/v1/users/me.
• KHÔNG áp dụng cho list endpoint — danh sách thay đổi liên tục (sản phẩm mới insert, sản phẩm cũ update), ETag list nhanh stale + tốn CPU compute hash toàn bộ collection.

Helper extractor preview (deep ở B62):

// File: crates/shop-api/src/extractors/if_none_match.rs (B62)
use axum::{extract::FromRequestParts, http::request::Parts};

pub struct IfNoneMatch(pub Option<String>);

impl<S> FromRequestParts<S> for IfNoneMatch
where S: Send + Sync,
{
    type Rejection = std::convert::Infallible;

    async fn from_request_parts(
        parts: &mut Parts,
        _state: &S,
    ) -> Result<Self, Self::Rejection> {
        let value = parts
            .headers
            .get("if-none-match")
            .and_then(|v| v.to_str().ok())
            .map(String::from);
        Ok(Self(value))
    }
}

Handler pattern (preview B62):

// File: crates/shop-api/src/routes/products.rs (B62 extend)
pub async fn get_product(
    Path(slug): Path<String>,
    IfNoneMatch(client_etag): IfNoneMatch,
    State(state): State<AppState>,
) -> Result<Response, AppError> {
    let product = products::find_by_slug(&state.db, &slug)
        .await?
        .ok_or(AppError::NotFound)?;

    let server_etag = format!(r#"W/"{}""#, product.updated_at.timestamp());

    if client_etag.as_deref() == Some(&server_etag) {
        return Ok(StatusCode::NOT_MODIFIED.into_response());
    }

    let mut response = Json(ProductResponseDto::from(product)).into_response();
    response.headers_mut().insert("etag", server_etag.parse().unwrap());
    Ok(response)
}

Lợi ích thực tế: GET catalog endpoint (product detail) tốc độ load second-visit user gần như instant — browser thấy 304 không cần parse body, hit cache. Áp dụng đúng pattern này tiết kiệm 60-80% bandwidth cho traffic catalog.

List endpoint trả về tập lớn cần chia trang. 2 chiến lược chính, mỗi cái có sweet spot riêng.

Offset pagination — ?page=2&per_page=20:

• SQL: SELECT ... LIMIT 20 OFFSET 20.
• Pros: đơn giản, intuitive cho user (jump tới trang 5 bằng 1 click), URL bookmark-able.
• Cons:
  • Performance giảm với offset lớn — Postgres phải scan rồi skip N row. OFFSET 1000000 trên catalog 10 triệu row tốn vài giây.
  • Inconsistent khi data thay đổi giữa 2 trang — sản phẩm mới insert đẩy mọi row xuống 1 vị trí, user thấy duplicate row hoặc miss row khi cuộn.

Cursor pagination — ?cursor=abc123&limit=20:

• SQL: WHERE created_at < $cursor ORDER BY created_at DESC LIMIT 20 (keyset query).
• Pros:
  • Performance constant — Postgres index seek thay scan, O(log n) bất kể vị trí trang.
  • Stable khi data thay đổi — cursor là điểm neo theo timestamp, row mới insert không ảnh hưởng vị trí hiện tại.
• Cons:
  • KHÔNG jump tới trang random (không có khái niệm "trang 5" trong cursor world).
  • Cursor opaque với user — token encode (timestamp + id) bằng base64.

Cursor encode format ví dụ:

cursor = base64(timestamp + "_" + id)

# Original: 2026-06-15T10:00:00Z_123
# Encoded:  MjAyNi0wNi0xNVQxMDowMDowMFpfMTIz

# Client gửi tiếp cho trang sau:
GET /api/v1/products/export?cursor=MjAyNi0wNi0xNVQxMDowMDowMFpfMTIz

Lock decision Shop API:

• Offset cho list endpoint user-facing (95% case) — UI catalog, admin dashboard có pagination control 1/2/3 truyền thống. Đã lock B23 với Pagination struct + ProductListResponse envelope.
• Cursor cho NDJSON export (data lớn, stable iter) — đã lock B49 với export_products_ndjson. Client là backend tool (ETL, analytics), không cần jump random trang.
• Cursor cho admin event stream (audit log, notification feed) — append-only data, cursor là pattern tự nhiên.

So sánh quick:

Tiêu chí               | Offset           | Cursor (keyset)
URL pattern            | ?page=N&per_page | ?cursor=opaque&limit
SQL                    | LIMIT/OFFSET     | WHERE col < cursor LIMIT
Performance N lớn      | Slow (scan+skip) | Fast (index seek)
Stability concurrent   | Drift duplicate  | Stable (point neo)
Jump random trang      | YES              | NO
Bookmark URL           | YES              | YES (opaque token)
Shop API use case      | UI catalog (95%) | Export + stream (5%)

Pattern chung: 95% case dùng offset (lock B23 page + per_page max 100), cursor chỉ cho special endpoint (NDJSON export, admin stream).

API public buộc phải versioning vì client (mobile app, third-party integration) không thể cập nhật ngay khi server thay đổi breaking. 3 cách công nghiệp:

• URL path — /api/v1/products (Shop API lock B7).
  • Pros: visible trong URL, cache-friendly (CDN cache theo path), dễ debug bằng browser, dễ test bằng curl.
  • Cons: URL phình to khi nhiều version song song.
• Accept header (vendor MIME) — Accept: application/vnd.shop.v1+json.
  • Pros: URL clean, semantic versioning rõ ràng.
  • Cons: khó debug (không thấy version trong URL), CDN cache phải kèm Vary: Accept, tooling client phức tạp.
• Query param — ?version=1.
  • Pros: dễ test.
  • Cons: dirty URL, không industry standard, dễ bị client quên gửi.

Lock decision Shop API: URL path /api/v1 (lock B7 continued + B24 router nest). Mỗi version có một router riêng, dễ maintain song song. GitHub API, Stripe API, Twilio API đều dùng pattern này.

Breaking change strategy:

• Minor change — thêm optional field, thêm endpoint mới: KHÔNG bump version. Client cũ vẫn hoạt động.
• Breaking change — bỏ field, đổi kiểu dữ liệu, đổi semantic: bump major version (/api/v2).
• Maintain v1 + v2 song song trong N tháng (deprecation period — Shop API mặc định 6 tháng, có thể extend tùy đối tác).

Báo trước breaking change qua Sunset header (IETF draft deprecation-header):

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Link: <https://shop.local/api/v2/products>; rel="successor-version"

{"items": [...]}

Client SDK đọc Deprecation: true và Sunset để cảnh báo developer migrate. Pattern lock cho Shop API khi rollout breaking change tương lai.

Pitfall thường gặp: tách /api/v1 và /api/v2 chia sẻ chung handler, dùng if version == "v2" trong code. Pattern này nhanh chóng biến thành spaghetti — Shop API lock route nest riêng từng version (Router::new().nest("/api/v1", v1_router).nest("/api/v2", v2_router)), code path tách biệt hoàn toàn.

Group 7 cover 15 bài (B61-B75) hoàn thiện CRUD đầy đủ cho 6 resource Shop API production-ready:

• B61 (bài này) — CRUD overview + resource modeling + idempotency + ETag + pagination + versioning.
• B62 — Products CRUD hoàn chỉnh: ETag header GET single + If-None-Match 304 + soft delete column.
• B63 — Products schema extend: variants (size/color), images, inventory tracking, audit log.
• B64 — Products endpoint full + admin restore endpoint + 2 helper extractor (IfNoneMatch, SoftDeleteScope).
• B65 — Soft delete pattern hoàn chỉnh: deleted_at column + query filter WHERE deleted_at IS NULL + admin un-delete via POST /restore.
• B66 — POST /api/v1/orders với create_order_atomic + Idempotency-Key Redis cache + retry strategy + handler đầy đủ.
• B67 — GET /api/v1/orders + filter status/user + reuse ProductFilter template lock B59.
• B68 — PATCH /api/v1/orders/{id} (cancel state machine) + POST /api/v1/orders/{id}/cancel action endpoint.
• B69 — Cart endpoints: GET /api/v1/cart + POST /api/v1/cart add item + DELETE clear.
• B70 — POST /api/v1/cart/items/{id} update qty + DELETE remove item + cart expiration policy.
• B71 — POST /api/v1/users/register + POST /api/v1/users/login (preview, deep G11 + G12).
• B72 — GET /api/v1/users/me + PATCH update profile + GET /api/v1/users/{id}/orders.
• B73 — Service layer abstraction (ProductService trait trong shop-core) + repository pattern + dependency injection.
• B74 — Domain error pattern: OrderError, CartError, UserError unified mapping qua impl From<DomainError> for AppError.
• B75 — End-to-end CRUD reuse pattern: macro #[derive(Crud)] hoặc generic handler factory (advanced topic, optional).

Sau Group 7, Shop API có 6 resource production-ready với CRUD đầy đủ, tổng cộng ~25 endpoint thực tế phục vụ user flow: browse catalog → add to cart → checkout → track order → user profile.

State workspace sau B61 KHÔNG đổi — bài này conceptual overview, foundation cho B62-B75 implement code thật từng resource.

• REST resource modeling: noun URL plural, hierarchy max 2 level, action verb POST cho non-CRUD.
• Idempotency vs Safe: GET/HEAD safe + idempotent; PUT/DELETE idempotent; POST không idempotent.
• PATCH idempotent KHI absolute value (B42 lock continued), KHÔNG khi delta.
• Idempotency-Key header lock cho POST /orders + POST /payments (B66 deep, Stripe-style).
• Shop API decision PATCH > PUT: PATCH cho user-facing 95%, PUT KHÔNG dùng (over-permissive).
• ETag weak W/"<updated_at_unix>" + 304 Not Modified cho GET single resource (không cho list).
• Pagination: offset cho UI (95% case lock B23), cursor cho NDJSON export (B49 lock) + admin stream.
• API versioning URL path /api/v1 lock B7 continued + nested router B24.
• Breaking change: bump major version + Sunset header + deprecation period N tháng.
• 15 bài Group 7 roadmap cho 6 resource: products + orders + carts + users + categories + payments.
• File path lock: extend crates/shop-api/src/routes/ cho mỗi resource (B62+).

Tự trả lời, đáp án ở cuối:

1. REST resource URL design: tại sao /products (số nhiều) thay /product (số ít)? Cho ví dụ pitfall khi sai convention.
2. Idempotent vs Safe — phân biệt 2 đặc tính. POST có thể idempotent không? Pattern Idempotency-Key giải quyết vấn đề gì?
3. PATCH với delta {"stock_delta": -1} không idempotent. Cho ví dụ scenario lỗi retry. Shop API quy ước thay thế là gì?
4. ETag weak vs strong — trade-off và Shop API chọn cái nào? Lý do.
5. Pagination offset vs cursor — performance khác nhau ra sao khi data 1 triệu row? Use case mỗi loại trong Shop API.

Bài 62: Products CRUD Hoàn Chỉnh — ETag + Soft Delete — bổ sung products endpoint: ETag header GET single + If-None-Match 304, soft delete với deleted_at column, restore endpoint admin, audit log trigger, áp Shop API full CRUD products pattern lock.