Chengdong Zhang
e10cae5789
Persist the modular-monolith decision (ADR 0001 handler/service/repo, ADR 0002 keep REST) with the companion tech spec and the api-architecture OpenSpec capability. Replace the finished mock-migration tracker with docs/TBD-marketing.md listing the backend-less marketing domains still on fixtures (coupons, favorites, account stats, seckill, collective, integral, reviews). README and AGENTS.md point at the new docs.
39 lines
1.7 KiB
Markdown
39 lines
1.7 KiB
Markdown
# 0002. Keep HTTP REST; do not replace the API with GraphQL
|
|
|
|
- Status: Accepted
|
|
- Date: 2026-09-18
|
|
- Deciders: VMall maintainers
|
|
- Related: [0001](0001-rust-api-modular-monolith.md)
|
|
|
|
## Context
|
|
|
|
The mall, shop-admin, and platform-admin apps share one typed REST client in `@vmall/shared`. Handlers already return composed DTOs (`ProductWithSkus`, `OrderView`, `CartView`). Command flows (checkout, pay, cancel, partial ship, issue invoice) are state machines with 409 conflicts and idempotent `UPDATE … WHERE status = …`.
|
|
|
|
A GraphQL rewrite was proposed to “modernize” the API.
|
|
|
|
## Decision
|
|
|
|
**Keep REST** on `/api/*`. Do not replace the public contract with GraphQL.
|
|
|
|
A **read-only GraphQL** endpoint for catalog browsing may be considered later if a third-party or mobile client needs arbitrary field sets. Write paths (checkout, stock, fulfillment, invoices) stay REST commands.
|
|
|
|
## Consequences
|
|
|
|
Positive:
|
|
|
|
- Existing OpenSpec HTTP scenarios, integration tests, and the mock adapter remain valid.
|
|
- Role checks stay on routes (`AuthUser::require_*`), not per GraphQL field.
|
|
- GET caching and payment/webhook-style POSTs stay straightforward.
|
|
|
|
Negative:
|
|
|
|
- Clients that want a custom nested graph still make several REST calls (already the case; DTOs cover storefront needs).
|
|
|
|
## Alternatives considered
|
|
|
|
**Full GraphQL (`async-graphql`) as the only API.** Rejected: would rewrite three apps, `@vmall/shared`, seed scripts, and all HTTP tests; field-level auth for three roles on one schema is harder to audit; N+1 needs DataLoaders; uploads and webhooks still want REST.
|
|
|
|
**JSON:API / sparse fieldsets.** Not needed while composed DTOs match the UIs.
|
|
|
|
**BFF per frontend.** Unnecessary while all three apps share one contract package.
|