bagisto 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
- 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.
- 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.