Bài 30: API Versioning: URL vs Header

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

• Hiểu vì sao API cần versioning — breaking change (đổi schema, rename field, remove endpoint) không tránh được nhưng client deployed không thể update đồng thời server, cần coexist nhiều version song song.
• Biết 3 approach versioning: URL versioning /api/v1, Header versioning qua vendor MIME Accept: application/vnd.shop.v2+json, Query versioning ?v=1.
• Phân biệt vendor MIME type application/vnd.<vendor>.<version>+json theo RFC 6838 với Accept header version đơn giản.
• Đọc được decision matrix trade-off mỗi approach trên 8 chiều: visibility, cache, browser test, tooling, pure-REST, industry adoption, discovery, routing code.
• Biết industry pattern lock từ production: Stripe, GitHub, AWS, Twitter, Twilio.
• Confirm Shop API chọn URL versioning /api/v1 (lock từ B5 vendor MIME đã loại + B24 nest đã apply) và roadmap migration v1→v2 4 phase với Deprecation/Sunset header theo RFC 8594.
• Biết folder structure khi có v2: crates/shop-api/src/routes_v2/ riêng giữ v1 stable.
• Hoàn thành Group 3 Routing Cơ Bản (10/10 bài) — chuẩn bị bước vào Group 4 Extractors Và Response Sâu.

API là contract (cam kết) giữa server và client: server hứa response shape không đổi để client parse được. Khi API có user thật (mobile app, third-party integration, partner system), contract đó trở thành ràng buộc cứng — server không thể tùy tiện đổi.

Breaking change (thay đổi phá vỡ tương thích) không tránh được sau vài tháng/năm vận hành:

• Đổi schema response — vd field price từ i64 cent sang {"amount": "12.50", "currency": "USD"} object để hỗ trợ multi-currency.
• Rename field — vd created → createdAt theo convention mới (camelCase + suffix At).
• Remove endpoint — vd /api/v1/legacy/checkout bị thay bằng /api/v1/checkout flow mới.
• Behavior change — vd GET /products mặc định trả 20 item giờ trả 50 item, hoặc thay đổi sort default.
• Đổi auth requirement — endpoint public giờ cần JWT, hoặc đổi scope cần thiết.

Client deployed KHÔNG thể update đồng thời server — đây là vấn đề cốt lõi:

• Mobile app: user cài app phiên bản cũ trên iOS/Android, không tự cập nhật cho đến khi mở App Store/Play Store. Có user dùng app version 1.2 từ 2 năm trước.
• Third-party integration: đối tác tích hợp API từ năm ngoái, không có resource cập nhật ngay khi server đổi contract — có thể mất 3-6 tháng để partner deploy fix.
• IoT/embedded device: firmware update hiếm (mỗi 6-12 tháng), không thể đẩy breaking change lên server.

Anti-pattern phổ biến: deploy breaking change KHÔNG version → toàn bộ client cũ break cùng lúc, support team flood, partner mất lòng tin, app store bị 1-star review hàng loạt. Versioning là cơ chế kỹ thuật giải bài toán này — cho phép server expose nhiều version cùng lúc, mỗi client tự chọn version phù hợp tốc độ release của mình.

API có version cũng làm rõ chính sách deprecation (gỡ bỏ): server cam kết duy trì v1 ít nhất 12 tháng sau khi v2 ra, đủ thời gian để client migrate.

URL versioning là approach phổ biến nhất 2026 — prefix version vào path URL:

GET /api/v1/products       → handler v1, schema cũ
GET /api/v2/products       → handler v2, schema mới
POST /api/v1/checkout      → handler v1 flow cũ
POST /api/v2/checkout      → handler v2 flow mới

Pros:

• Visibility cao — dev đọc URL biết version ngay không cần xem header hay query. Log line GET /api/v1/products tự nói version.
• Cache CDN dễ — URL khác = cache key khác, không cần Vary header phức tạp; CloudFront/Cloudflare/Fastly cache theo URL mặc định.
• Browser bookmark + share link + debug curl trivial — paste URL trình duyệt là test được endpoint GET, không cần set header.
• Tooling universal — Postman/Swagger UI/Insomnia/Bruno hiển thị version rõ trong sidebar collection.
• Routing code đơn giản — framework nào cũng support prefix routing (axum nest, Express app.use('/api/v1', router), Spring @RequestMapping("/api/v1")).
• Discovery dễ — client mới đọc doc thấy https://api.shop.com/api/v1/products hiểu ngay version 1.

Cons:

• URL "không thuần REST" — purist theo Roy Fielding cho rằng resource URL không nên có version, vì version là thuộc tính representation chứ không phải resource. Trong thực tế tranh luận này ít có giá trị thực tiễn — Stripe/GitHub/AWS đều dùng URL versioning.
• Routing code có thể duplicate — nếu v2 chỉ khác v1 ở 2-3 endpoint, vẫn phải khai báo lại toàn bộ sub-router. Khắc phục bằng cách share handler v1 với những endpoint không đổi.

Shop API decision: dùng URL versioning, lock từ B5 (vendor MIME đã loại) và đã apply ở B24 qua Router::nest. Code router.rs hiện tại:

// File: crates/shop-api/src/router.rs (sau B25)
pub fn build_router(state: AppState) -> Router {
    let api_v1 = Router::new()
        .merge(routes::products::routes());

    Router::new()
        .route("/", get(root))
        .merge(routes::health::routes())
        .merge(routes::version::routes())
        .nest("/api/v1", api_v1)   // ← URL versioning prefix
        .fallback(handlers::fallback::not_found)
        .with_state(state)
}

Khi cần v2: thêm đúng 1 sub-router + 1 dòng nest() nữa, KHÔNG đụng v1.

Header versioning gửi version qua Accept header. Convention chuẩn là vendor MIME type theo RFC 6838: application/vnd.<vendor>.<version>+json — prefix vnd. nghĩa "vendor-specific" (không phải MIME chuẩn IANA).

# Request v1
curl -H "Accept: application/vnd.shop.v1+json" \
     https://api.shop.com/products

# Request v2
curl -H "Accept: application/vnd.shop.v2+json" \
     https://api.shop.com/products

# Server parse Accept → route đến handler v1 hoặc v2

URL /products giữ nguyên không phụ thuộc version — resource identity không đổi theo triết lý Roy Fielding.

Pros:

• URL stable — không cần /v1, /v2 trong path; resource identity giữ nguyên trọn lifecycle API.
• "Pure REST" theo Fielding — version là thuộc tính của representation (Accept negotiate), không phải resource (URL).
• Resource discovery clean — Swagger spec mô tả URL ổn định, doc không đầy /v1/....

Cons:

• Tooling pitfall — curl phải set -H "Accept: ..." mỗi lần, Postman phải config header per request, Bruno phải khai báo trong env. Quên header → server fallback default version, dễ bug âm thầm.
• Browser KHÔNG thể test trực tiếp — type URL vào address bar gửi Accept: text/html, không phân biệt được version → dev không thể quick test GET endpoint trình duyệt.
• Cache CDN phức tạp — cùng URL nhưng response khác theo Accept → cần Vary: Accept header, CDN phải store nhiều variant per URL; hit rate giảm; CloudFront/Cloudflare cấu hình phức tạp hơn.
• Discovery khó — không nhìn URL biết version đang gọi, phải xem doc hoặc inspect request header.
• Log analysis khó — log line GET /products không nói version, phải log thêm Accept header để biết — tốn disk, parser phức tạp.

Industry use: GitHub REST API dùng Accept: application/vnd.github.v3+json kết hợp URL /api/v3 — hybrid pattern.

Shop API KHÔNG dùng vendor MIME — lock từ B5: tooling pitfall + browser test inconvenience + cache phức tạp quá nhiều cho lợi ích "pure REST" thuần lý thuyết. Team nhỏ ưu tiên visibility + tooling universal hơn purity.

Query versioning gửi version qua query string:

curl https://api.shop.com/products?v=1
curl https://api.shop.com/products?v=2
curl https://api.shop.com/products?api_version=2024-06-20

Pros:

• Simple cho client — chỉ thêm query parameter, không cần set header.
• Browser test được — paste URL với ?v=2 vào address bar work.
• Tooling support — curl/Postman handle query string mặc định.

Cons:

• URL không stable — cùng resource có 2 URL (/products?v=1 vs /products?v=2), bookmark/share link khó.
• Mixed concern — query string thường dùng cho filter/pagination/sort (?page=1&size=20), trộn version vào dễ confusing với business param.
• Optional default ambiguous — không gửi v thì server dùng version nào? Latest? Earliest? Mỗi lựa chọn đều có pitfall.
• Cache CDN ambiguous — query khác = key khác mặc định, nhưng nếu CDN cấu hình strip query → cache nhầm version (anti-pattern phổ biến CloudFront default behavior).
• Routing code awkward — phải parse query trong handler để dispatch sang handler tương ứng version, không tách bạch ở router level.

Industry use: rất ít. Twitter API v1.1 trước đây có ?api_version nhưng đã loại khi chuyển sang Twitter v2 URL-based. Stripe có header Stripe-Version (custom header riêng, không phải query). Hiện 2026 không có API public lớn nào dùng query versioning làm primary.

Shop API KHÔNG dùng — mixed concern với filter/pagination là deal-breaker. Lock URL versioning từ B5.

Bảng so sánh 8 chiều giúp quyết định approach phù hợp:

Aspect              │ URL `/v1`          │ Header             │ Query `?v=1`
────────────────────┼────────────────────┼────────────────────┼──────────────────
Visibility          │ High               │ Low                │ Medium
Cache CDN           │ Easy (URL key)     │ Need Vary: Accept  │ Easy if not strip
Browser test        │ Yes                │ No                 │ Yes
Tooling             │ Universal          │ Need header set    │ Universal
"Pure REST"         │ No (purist view)   │ Yes (Fielding)     │ Mixed concern
Industry adoption   │ Stripe, AWS,       │ GitHub (hybrid),   │ Rare (Twitter
                    │ Twitter v2, Twilio │ HATEOAS demo       │ legacy bỏ)
Discovery           │ URL clear          │ Schema doc         │ URL + query
Routing code        │ Duplicate per ver  │ Branch in handler  │ Branch in handler

Khuyến nghị:

• URL versioning cho hầu hết case — visibility cao + tooling universal + cache đơn giản thắng cho team < 50 người, project < 5 năm.
• Header versioning chỉ khi cần "pure REST" cho HATEOAS hypermedia API hoặc team tooling-ready (Postman collection auto-set header, CI test framework set sẵn).
• Query versioning không nên dùng — mixed concern + cache ambiguous + không industry pattern lớn nào dùng làm primary.
• Hybrid URL + custom header như Stripe (/v1/... + Stripe-Version: 2024-06-20) cho fine-grained per-account version — pattern advanced, chỉ áp dụng khi cần backward compat per-merchant như payment processor.

Shop API chọn URL versioning thuần — đủ cho roadmap 3 năm tới, có thể bump v2 khi schema thay đổi major.

Phân tích pattern từ 5 production API lớn nhất 2026:

Provider │ Primary Versioning      │ Secondary       │ Pattern
─────────┼─────────────────────────┼─────────────────┼──────────────
Stripe   │ URL /v1/charges         │ Stripe-Version  │ URL + custom
         │                         │ 2024-06-20      │ header hybrid
         │                         │ per-account     │ date-based
GitHub   │ URL /api/v3/repos       │ Accept vnd.     │ URL + vendor
         │                         │ github.v3+json  │ MIME hybrid
AWS      │ URL /2024-01-01/...     │ —               │ URL date-based
Twitter  │ URL /2/tweets           │ —               │ URL numeric
Twilio   │ URL /2010-04-01/        │ —               │ URL date-based
         │ Accounts                │                 │

Stripe dùng URL /v1/charges cho path đồng thời custom header Stripe-Version: 2024-06-20 per request hoặc per account. Dashboard cho merchant chọn account version mặc định, override per request qua header. Hybrid pattern advanced cho payment processor cần fine-grained backward compat — không khuyến nghị cho team mới.

GitHub REST API dùng URL /api/v3/repos nhưng cũng chấp nhận Accept: application/vnd.github.v3+json để client explicit yêu cầu version. Header có thể chỉ định media type cụ thể như application/vnd.github.v3.raw cho raw content hoặc .html cho rendered HTML — combine versioning với content negotiation.

AWS dùng date-based version /2024-01-01/... trong URL — mỗi service có endpoint riêng https://<service>.<region>.amazonaws.com/2024-01-01/.... Date format ISO 8601 nói rõ "version of API as of this date" — dễ chọn version stable.

Twitter API v2 dùng URL numeric /2/tweets sau khi loại bỏ query ?api_version của v1.1. Migration công khai (deprecation notice 12 tháng) trở thành case study đáng học.

Twilio dùng URL date-based /2010-04-01/Accounts — version từ năm 2010 vẫn maintain để client legacy không break. Cam kết backward compat dài hạn của Twilio là điểm bán hàng cho enterprise.

Pattern phổ biến chung: URL versioning là primary cho mọi public API lớn. Header (vendor MIME hay custom) chỉ là secondary cho hybrid pattern advanced. Query versioning hầu như đã biến mất khỏi production API 2026.

State hiện tại: Shop API đang ở v1, mọi resource mount dưới prefix /api/v1 qua nest("/api/v1", api_v1) trong build_router() (lock B24). URL effective: /api/v1/products, /api/v1/cart, /api/v1/orders, v.v.

Khi nào bump v2? Chỉ khi có breaking change không thể avoid:

• Đổi schema response major — vd price từ cent integer sang Money object multi-currency.
• Remove field/endpoint không backward-compat — vd loại bỏ field legacy_id đã deprecated 12 tháng.
• Đổi behavior default — vd GET /products đổi sort default từ createdAt sang relevance.
• Đổi auth scope — endpoint cũ public giờ cần JWT, hoặc đổi required scope.

Non-breaking change KHÔNG bump version — thêm field mới optional, thêm endpoint mới, thêm query param optional đều backward-compat với client cũ. Chỉ bump v2 cho breaking change thật.

Migration strategy 4 phase lock cho Shop API:

Phase 1: Deploy v2 song song v1
  - Tạo folder routes_v2/ riêng
  - Thêm nest("/api/v2", api_v2) vào router.rs
  - v1 vẫn 100% như cũ, KHÔNG sửa
  - Test v2 internal, không announce public

Phase 2: Public announce v2
  - Update OpenAPI doc (B8) với cả v1 + v2 spec
  - Mark v1 endpoint với "deprecated: true" trong OpenAPI
  - Blog post / email partner announce v2 ready
  - Khuyến khích client mới integrate v2

Phase 3: Add Deprecation/Sunset header v1
  - Response v1 thêm header per RFC 8594:
      Deprecation: true
      Sunset: Wed, 01 Jan 2027 00:00:00 GMT
      Link: <https://docs.shop.com/v2-migration>;
            rel="deprecation"
  - Client phát hiện header, plan migrate

Phase 4: Gradually shutdown v1
  - Monitor metrics: % traffic v1 vs v2 mỗi tuần
  - Email client còn dùng v1 (qua API key tracking)
  - Khi v1 traffic dưới 5%, set sunset date final
  - Sunset: trả 410 Gone với link migration doc

Code preview khi có v2:

// File: crates/shop-api/src/router.rs (preview khi có v2)
pub fn build_router(state: AppState) -> Router {
    let api_v1 = Router::new()
        .merge(routes::products::routes());        // v1 schema cũ giữ nguyên

    let api_v2 = Router::new()
        .merge(routes_v2::products::routes());     // v2 schema mới

    Router::new()
        .merge(routes::health::routes())
        .merge(routes::version::routes())
        .nest("/api/v1", api_v1)                    // v1 vẫn serve
        .nest("/api/v2", api_v2)                    // v2 song song
        .fallback(handlers::fallback::not_found)
        .with_state(state)
}

Folder structure khi có v2 — lock pattern: tạo folder routes_v2/ riêng, KHÔNG sửa file routes/ v1 cũ:

crates/shop-api/src/
├── routes/                  ← v1 stable, KHÔNG sửa
│   ├── mod.rs
│   ├── products.rs
│   ├── cart.rs
│   └── ...
├── routes_v2/               ← v2 mới
│   ├── mod.rs
│   ├── products.rs          ← schema mới
│   └── ...
├── handlers/
├── dto/                     ← v1 DTO giữ nguyên
├── dto_v2/                  ← v2 DTO mới (nếu schema khác)
└── router.rs                ← nest cả v1 và v2

Lý do tách folder riêng thay vì branch if version == 2 trong handler:

• Cô lập rủi ro — sửa v2 không thể accidentally break v1.
• Code review dễ — diff v2 chỉ trong routes_v2/, reviewer không cần check v1 có bị đụng không.
• Test riêng — test suite v1 + v2 tách bạch, regression riêng.
• Delete v1 dễ khi sunset — chỉ cần xóa folder routes/ + dòng nest("/api/v1", ...), không phải refactor nhánh logic phức tạp.

RFC 8594 (Sunset HTTP Header Field, 2019) chuẩn hóa Sunset header với date format RFC 7231 (HTTP-date). RFC mới hơn cho Deprecation header (draft IETF) đang được nhiều API adopt — Shop API lock cả 2 header cho phase 3.

• API versioning cần để coexist nhiều client version (mobile app, third-party integration, IoT device) không thể update đồng thời server — versioning là contract giữa server và client.
• Breaking change không tránh được: đổi schema, rename field, remove endpoint, behavior change, đổi auth scope — anti-pattern deploy breaking không version → break toàn client cùng lúc.
• 3 approach: URL /api/v1 (visibility cao + tooling universal), Header vendor MIME Accept: application/vnd.shop.v2+json (pure REST, URL stable), Query ?v=1 (rare, mixed concern).
• Decision matrix 8 chiều: URL thắng visibility/cache/browser/tooling/discovery; Header thắng pure-REST/URL-stable; Query không thắng chiều nào quan trọng.
• Industry pattern 2026: Stripe (URL + Stripe-Version hybrid), GitHub (URL + vendor MIME hybrid), AWS (URL date-based), Twitter v2 (URL numeric), Twilio (URL date-based) — đều dùng URL làm primary.
• Shop API lock URL versioning /api/v1 — confirm từ B5 (vendor MIME loại) + B24 (nest("/api/v1", api_v1) apply); đổi v1→v2 chỉ 1 dòng nest() thêm.
• Migration v1→v2 lock 4 phase: (1) deploy song song routes_v2/, (2) OpenAPI document v1 deprecated, (3) header Deprecation: true + Sunset: <RFC 7231 date> theo RFC 8594, (4) monitor metrics + email client + gradually shutdown.
• Folder structure khi có v2: crates/shop-api/src/routes_v2/ riêng giữ v1 stable — cô lập rủi ro, code review dễ, test riêng, delete v1 trivial khi sunset.
• Non-breaking change (thêm field optional, thêm endpoint, thêm query param) KHÔNG bump version — backward-compat với client cũ.
• HOÀN THÀNH Group 3 Routing Cơ Bản (10/10 bài) — sẵn sàng vào Group 4 Extractors Và Response Sâu từ B31.

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

1. Tại sao API cần versioning? Mô tả anti-pattern nếu deploy breaking change KHÔNG version, và hệ quả cho client mobile/third-party.
2. 3 approach versioning. Approach nào visibility cao nhất? Tại sao log line + browser test + discovery đều dễ hơn?
3. Header versioning với Accept: application/vnd.shop.v2+json. Liệt kê 3 tooling pitfall khi dùng vendor MIME trong production.
4. Shop API chọn URL versioning /api/v1. Industry pattern nào tương tự (chỉ 3 ví dụ)? Pattern hybrid của Stripe khác gì pattern thuần URL của Twitter v2?
5. Migration v1→v2 lock 4 phase. Liệt kê ngắn gọn từng phase + nêu RFC nào chuẩn hóa Sunset header.

Bài 31: Extractor Trait — Bản Chất — bắt đầu Group 4 Extractors Và Response Sâu: trait FromRequestParts + FromRequest, axum chạy mỗi extractor tuần tự, fail nhanh khi 1 fail, order matters (body extractor cuối). Chuẩn bị tạo custom extractor cho Shop API.