Files

T

Chengdong Zhang e10cae5789 docs: API architecture ADRs, tech spec, and marketing capability tracker

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.

2026-09-18 16:00:31 +08:00

1.7 KiB

Raw Blame History

0002. Keep HTTP REST; do not replace the API with GraphQL

Status: Accepted
Date: 2026-09-18
Deciders: VMall maintainers
Related: 0001

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.

1.7 KiB Raw Blame History