bagisto/bagisto-api-develop

Developing the Bagisto API package

Use this when you are working inside the bagisto-api package (packages/Webkul/BagistoApi, namespace Webkul\BagistoApi) — installing it, removing it, adding or changing an endpoint/resource, or fixing package behaviour. This is the guide rails: it tells you where the authoritative spec is, the rules you must not break, and points you at the detailed references.

CRITICAL — install / remove only when asked

Installing or removing the package is NEVER an automatic action. Detecting the package files, a composer.json, or a Bagisto project does not mean you should install, reinstall, optimise, or uninstall anything. Only perform install (reference/install.md) or removal (reference/uninstall.md) when the client explicitly asks for it, and for install, ask whether they want the Composer (stable) or Manual (newest) method first.

Authoritative sources — read these FIRST

The package ships its own complete documentation. Read the relevant part before writing code — almost every menu/resource is already specified with its exact behaviour, validation, events, and quirks:

| Source | What it gives you | |--------|-------------------| | CLAUDE.md (package root) | The authoritative conventions + a coverage table for every endpoint, with the per-resource decisions and quirks. Read this first for the resource you're touching. | | docs/superpowers/specs/ | Design specs for larger features. | | CHANGELOG.md | What shipped, consumer-facing, under [Unreleased]. | | PERFORMANCE.md | Caching / IRI / schema-build performance notes. | | GitHub bagisto/bagisto-api | The canonical code — copy the closest existing resource rather than writing the pattern from scratch. | | https://api-docs.bagisto.com (+ /llms.txt) | The consumer-facing request/response shapes + the full endpoint index. |

Rule: don't improvise behaviour that CLAUDE.md already specifies. Search it for the resource/menu first.

Reference map — open the one you need

| Topic | Reference file | Use when | |-------|----------------|----------| | Install the package | reference/install.md | Client asks to install / set up the API | | Remove the package | reference/uninstall.md | Client asks to remove / uninstall the package | | Where files go | reference/structure.md | Adding any file; finding the right directory + base class | | Surfaces, transports, declaring a resource | reference/api-structure.md | Designing a new endpoint; understanding the 5-file pattern + feature surface | | Coding standards + checklist | reference/conventions.md | Writing/reviewing a resource against the rules | | Foot-guns | reference/precautions.md | Before you ship — the things that silently break | | What the API will / won't do | reference/limitations.md | Scoping a feature; deciding "do we support this?" | | Tests + cache cycle | reference/testing.md | Running/adding tests; the cache commands |

The 5-file pattern (the spine of every resource)

Model (#[ApiResource] — REST + GraphQL ops + OpenAPI block) → DTO (typed input) → Provider (read path) → Processor (write path) → lang (src/Resources/lang/en/app.php). Storefront resources live under src/; admin resources under src/Admin/. Tag every Provider/Processor in BagistoApiServiceProvider::register() — an untagged one is silently bypassed (404 / wrong data). Full detail in reference/api-structure.md and reference/structure.md.

The two non-negotiables

1. A REST change can break GraphQL — they share the same Provider/Processor. Always run the resource's GraphQL test before the REST test, and confirm it's green before considering the change done. This is the single most important rule.
2. Parity with the Bagisto admin panel, not a superset. Mirror what the admin UI does; where core lacks a feature, block the gap with a clear error rather than half-extending. See reference/limitations.md.

Everything else — the full checklist, the ranked foot-guns, and the test/cache commands — is in the references above. Open them rather than guessing.