Rest Api Laravel Package

Product Decisions This Supports

• Headless/composable commerce go-or-no-go. bagisto/rest-api is the dependency that decides whether Bagisto can back non-Bagisto surfaces — native apps, SPAs, PWAs, kiosks, partner portals, marketplace connectors. If "launch a mobile app" or "decouple the storefront" is on the roadmap, this package reframes the question from platform rebuild to sequencing: what ships first, on which channel, against which endpoints.
• Build vs. buy for the API layer. The counterfactual is expensive and easily underestimated: resource modeling, token auth, cart/checkout serialization, versioning, documentation, and the permanent support burden. Because it exposes catalog, product, category, customer auth, cart, checkout, and orders out of the box, the buy case is unusually clean. This deserves a dated decision record — including the headcount you would need to staff the build and the months before the first external client could integrate.
• Channel expansion sequencing. Ready-made endpoints let new channels be planned as integrations rather than rebuilds, which changes effort estimates, which changes what you can credibly commit to and when. It is a roadmap lever that buys earlier channel-launch promises — but only if the version pin against Bagisto core is treated as a first-class constraint, not an afterthought.
• Partner and integrator ecosystem policy. Token auth plus configurable, route-level access means you can decide which capabilities go to whom — catalog read-only for affiliates, full checkout for a vetted partner — as configuration rather than custom code. That is a commercial and data-sharing lever (partner tiers, exposure boundaries, pricing visibility) and product should own it deliberately rather than let defaults decide it. Audit the default exposure before the first partner gets a key.
• Cost and perceived-speed trade-offs. v2.3.1's ETag support turns repeat reads into 304 Not Modified. Frame it as a lever on CDN egress, origin load, and mobile latency on read-heavy catalog traffic — speed you buy without a client migration. Deliberately scope it to catalog/category/product detail, not cart, checkout, customer, or orders, where personalized responses make the correctness risk outweigh the bandwidth win.
• Documentation as a delivery asset. The refreshed Swagger spec is a shippable artifact: it shortens integrator onboarding and is the fastest way to see request/response shapes. Treat spec-vs-runtime drift as a quality metric, not a documentation chore.

When to Consider This Package

Adopt when:

• You are already on Bagisto (roughly 2.3.x, in lockstep with the package). This is a presentation layer over the Bagisto domain model — it does not port to vanilla Laravel, and nothing here transfers if you are not on Bagisto.
• You need one or more non-Bagisto clients — mobile app, SPA, PWA, partner integration — and you need authenticated cart and checkout, not just catalog reads.
• You want partner-tier access control as configuration rather than per-partner code branches.
• You can accept ownership. At 28 stars and zero known dependents, community answers will not arrive on your timeline. Adopt only with a named internal owner for the API layer and a local patch workflow (Composer patches or a fork) ready.
• You can pin tightly and re-verify on every Bagisto upgrade. Drift does not fail loudly — it surfaces as subtly wrong serialization or a changed repository method signature.

Look elsewhere when:

• You are not on Bagisto, or you are on a materially different Bagisto version and cannot move. The version-skew failure mode is confusing model/repository mismatches, not a clean install error.
• You need a fully supported, SLA-backed commercial API product. This is first-party infrastructure you operate, not a vendor-supported platform.
• Your API needs are write-heavy and custom-domain (bespoke pricing engines, non-standard fulfillment, event-driven integrations) beyond catalog/cart/checkout primitives — you will spend the savings extending rather than composing.
• You cannot staff a support tier or tolerate reading vendor source. Zero dependents means zero collective debugging.
• You need guaranteed spec fidelity. If the spec is hand-maintained rather than generated from annotations, treat it as documentation with a shelf life and budget smoke tests accordingly.

How to Pitch It (Stakeholders)

For executives: This is the cheapest credible path to selling through channels other than the website. Without it, "expose our store to external clients" is a multi-quarter internal program — resource design, authentication, checkout serialization, versioning, docs, and ongoing support. With it, that scope collapses into configuration plus integration work. That is not a vendor-lock claim; it is a build-vs-buy call where the buy side is dramatically smaller, and we should record the decision and the counterfactual cost explicitly.

For engineering: It is a REST layer over the existing Bagisto domain, released roughly in lockstep with core — so the real risk is version skew, not integration complexity. Plan for a tight Composer constraint, a Bagisto-upgrade checklist that includes re-running API smoke tests, and a local patch workflow. Extend the package's controllers and JsonResource classes rather than writing parallel ones, so response envelopes, pagination shape, and ETag middleware behavior stay consistent across built-in and custom routes. Wrap the API in a single client service with shared base URL, token handling, and ETag caching — do not scatter Http:: calls across consumers. Feature-test against a seeded store plus a small contract suite; fakes will not catch eager-loading serialization bugs.

For security and compliance: Route-level access control in this package is configuration, and the default exposure is a decision we inherit unless we change it. Before any partner key is issued, we review which capabilities are exposed — read-only catalog versus cart mutation versus customer data — and we make different partner tiers different configurations, not different code branches. On the ETag work in v2.3.1: authenticated responses must carry Cache-Control: private and a Vary including Authorization. We verify with two different tokens on a cart endpoint that tags differ; if they do not, we disable ETag on personalized routes rather than reason about it. ETags are never emitted on 4xx/5xx.

For support and customer-facing teams: One paragraph in integrator onboarding removes a recurring ticket class — cache the body, send If-None-Match, reuse the body on 304. 304 is a success, not an error. Give on-call a documented lever to disable the ETag middleware mid-incident; not having that lever converts a cache bug into an outage. Triage stale-data reports in order: client cache, proxy cache, origin.

The honest caveat to state up front: 28 stars and zero known dependents means we are the support tier. That is acceptable for first-party infrastructure we would otherwise build — but we plan for it deliberately rather than discover it mid-incident.