Bagisto Api Laravel Package

Product Decisions This Supports

• Headless storefront / mobile app roadmap. The package removes the "build an API layer first" tax from any plan to ship a PWA, native app, kiosk, or POS client. The decision flips from build vs. buy to adopt vs. defer: REST and GraphQL surfaces, storefront key auth, rate limiting, Swagger docs, and GraphQL playgrounds are already specified.
• Integration portfolio prioritization. ERP, PIM, CRM, 3PL, and marketplace connectors all need the same read/write primitives (catalog, customers, cart/checkout, orders, invoices, shipments, refunds, wishlist, reviews). Because both shop and admin surfaces exist, you can sequence integrations by business value rather than by API availability.
• Build vs. buy on API infrastructure. Buying here means inheriting API Platform for Laravel (~4.3.8) rather than maintaining a bespoke controller/DTO/serializer layer. The trade is dependency on API Platform's upgrade cadence and on Bagisto core version alignment — a scoping decision, not a feature decision.
• Admin automation and internal tooling. Integration tokens are scoped to a single admin user and inherit that admin's role permissions, so you can green-light bulk order ops, catalog maintenance, and back-office companion apps without inventing a parallel permission model. The announced GET /api/admin/menu and /api/admin/permissions endpoints strengthen this for permission-aware admin UIs.
• Partner / developer ecosystem. Exported OpenAPI JSON and GraphQL SDL (bagisto-api-platform:export-schema) plus ready-made Postman collections turn "can we let partners integrate?" into a distribution problem. Schema export also enables generated SDKs and mock servers without a live environment — a real lever for reducing integration support load.
• Performance and SLO commitments. The changelog's ~1.5s → ~0.3s GraphQL list improvement (with bagisto-api-platform:optimize and APP_DEBUG=false) directly informs whether you can promise sub-second list endpoints or need to budget for a caching/CDN layer in front.
• Release and upgrade planning. The package version-tracks Bagisto (2.x, tested against v2.4.7), so API work sits inside the platform upgrade train rather than beside it. Treat Bagisto upgrades as API-contract changes in roadmap planning.

When to Consider This Package

Adopt when:

• You are running Bagisto v2.4.x (CI-tested against 2.4.7) on PHP 8.3+, MySQL 8.0+/PostgreSQL 14+, with Composer 2.
• You need both REST and GraphQL, and both storefront and admin surfaces — the package scopes each surface separately and refuses to export a schema that leaks across them, which is a meaningful governance property for external partners.
• You want fast time-to-first-integration: one composer require + bagisto-api-platform:install, then docs at /api/shop/docs, /api/admin/docs, and playgrounds at /api/graphiql and /api/admin/graphiql.
• Your team is small enough that owning an API Platform integration is not a differentiator.
• You can operate the deployment hygiene the package expects: APP_DEBUG=false, route/config caching, running bagisto-api-platform:optimize after deploy.

Look elsewhere (or budget for mitigation) when:

• You are not on Bagisto — the package is tightly bound to Bagisto/Webkul domain models and service providers; it is not a general Laravel e-commerce API.
• You need OAuth2/OIDC, SSO, or fine-grained scopes beyond "one token per admin, inherits role permissions." Storefront uses API keys and admin uses integration bearer tokens; that is a simpler model than enterprise identity requirements typically demand.
• You need a mature, battle-tested public contract. Signals are thin: 9 stars, 0 dependents, a first release in the 1.0.x line, and a changelog where 403 permission bugs, missing sort/order on wishlist and address listings, and cache-clear timeouts are still being fixed. That is normal for a young first-party package, but it is not a "bet your partner ecosystem on it untouched" maturity level.
• You need vendor SLAs, LTS commitments, or a large external contributor base. MIT and first-party is good; 9 stars and no dependents means you will be largely self-supporting via GitHub issues and the forum.
• You require deep, non-standard customization of resource definitions — you will be working inside API Platform metadata, and customizations may be fragile across versions, especially with API Platform pinned (~4.3.8).
• Onboarding friction is unacceptable for admin users: the Integration menu stays hidden until the module is enabled under Configuration → API → Integration, and plaintext tokens are shown exactly once. That is a documented support burden to plan for.

How to Pitch It (Stakeholders)

To executives: This is an open-source (MIT), first-party API layer for our Bagisto commerce platform that gives us production-shaped REST and GraphQL endpoints for both the storefront and admin — the plumbing every mobile app, partner integration, and back-office tool needs. It converts a multi-month API build into a Composer install plus a deployment checklist, with generated API specs and Postman collections to accelerate third parties. The cost is dependency and maturity risk, not license cost: the package is young (9 stars, 0 dependents) and version-locked to Bagisto and API Platform. We mitigate by pinning versions, generating and diffing schemas in CI as contract tests, and scoping initial exposure to internal consumers before opening it to partners.

To engineering: Built on API Platform for Laravel (~4.3.8) with REST and GraphQL for shop and admin, storefront key auth with rate limiting, admin integration tokens scoped to the owning admin's role permissions, schema export via bagisto-api-platform:export-schema, and bagisto-api-platform:optimize for cache warming (reported ~1.5s → ~0.3s on GraphQL lists). Requirements are PHP 8.3+, Bagisto 2.4.7, MySQL 8/PG 14. Known sharp edges to own: APP_DEBUG=false in production, admin module must be enabled before Integration settings appear, and admin/menu and admin/permissions endpoints are still "Coming."

Positioning in one line: Adopt it as the default integration layer for our Bagisto roadmap, gate external partner access on a schema-contract test suite and one internal production consumer, and revisit if Bagisto upgrades or API Platform pinning become a delivery constraint.