Api Toolbox Laravel Package

Product Decisions This Supports

• Build vs. buy for API conventions. The package covers the unglamorous, high-rework parts of a JSON API — problem-details error responses, pagination, Prefer/PATCH semantics, locking and retries, webhooks, and request/response signing. These are commodity concerns where in-house implementations reliably diverge across teams; this is a candidate "adopt, don't build" decision.
• API standards rollout. A single package that defines error/problem types, retry semantics, and pagination gives you one enforcement point instead of a wiki page. The Features flags also make it a staged rollout decision: enable capability by capability rather than a big-bang API rewrite.
• AI-assisted development strategy. The Laravel Boost guideline and api-toolbox-development skill mean coding agents receive correct, package-specific instructions on first contact. Combined with the test that verifies every referenced class, constant, middleware alias, assertion and method exists and every snippet parses, this is a concrete argument for (or against) treating agent-readiness as a procurement criterion in your toolchain.
• Supportability and incident response. The php artisan about section (version, per-feature on/off incl. experimental flags, signature key IDs and algorithms — never secrets or key paths) is a first-class operational decision: it determines how fast on-call can triage a signing or feature-flag issue, and it demonstrates a security-conscious default for diagnostics output.
• Roadmap sequencing. The explicit Features::EXPERIMENTAL list gives a defensible way to phase adoption: ship GA features to production now, hold experimental ones behind a flag until you have bandwidth for minor-release churn.
• Interop and documentation. Digest problem types now sourced from the generated apiguide.dev catalogue with unchanged type URIs means the package's public error contract is externally documented and stable — useful for partner-facing API decisions and third-party integration negotiations.

When to Consider This Package

Consider adoption when:

• You are building or standardizing a consumable JSON API on Laravel (partners, mobile clients, or internal services with real SLAs) where error shape, pagination, retries and webhooks need to be consistent.
• You have more than one team or service producing APIs and are paying for inconsistency in error formats or idempotency behavior.
• AI coding agents are part of your workflow — the Boost guideline and skill materially reduce the "agent invents an API that doesn't exist" failure mode, and the verification test makes that a maintained guarantee rather than a claim.
• Operational clarity matters — you want feature state and signing-key algorithms visible in artisan about during incidents without shelling into secret stores.
• You want to buy/borrow API conventions rather than fund an internal standards library and its long-term ownership.

Look elsewhere or defer when:

• Version maturity is a blocker. This is a 0.x release; anything marked Features::EXPERIMENTAL may change in a minor release. If you need LTS guarantees or a frozen public contract, that is a real constraint, not a detail.
• You need contract-first OpenAPI as the source of truth. This package expresses conventions in code; it is not an IDL/spec generator.
• Your APIs are internal-only and single-consumer, where bespoke error handling costs little and an extra dependency costs more.
• You are not on the supported Laravel/PHP range, or your platform team has a policy against pre-1.0 dependencies in critical request paths.
• You need multi-framework or non-Laravel coverage — this is Laravel-native by design.

How to Pitch It (Stakeholders)

For executives (one paragraph): We are standardizing the repetitive, error-prone parts of our APIs — how errors are reported, how clients retry safely, how requests are signed, how lists paginate. That work is currently rebuilt per service, which is where most cross-team inconsistency and post-incident rework comes from. This package replaces that bespoke effort with a maintained Laravel-native implementation, and its newest release adds two things that directly reduce our cost of ownership: machine-readable operational visibility (artisan about reports version, enabled features and signing-key algorithms — never secrets), and first-class guidance for the AI coding agents our engineers already use, with automated tests that keep that guidance factually accurate. Risk is bounded and explicit: it is pre-1.0, and the package itself enumerates which features are experimental and may shift in a minor release, so we can adopt the stable surface now and gate the rest. Recommended decision: pilot on one API in the next cycle and evaluate against the stable feature set.

For engineering leads: The agent-facing guideline plus the api-toolbox-development skill are the headline. A test asserts every class, constant, middleware alias, assertion and method the docs mention actually exists, and that every PHP snippet parses — so the documentation cannot silently rot, and agents stop hallucinating our API surface. php artisan about --only=api_toolbox gives on-call a single command for feature state and key IDs/algorithms without touching secrets. The Features::EXPERIMENTAL constant gives us a clean dependency policy: pin the stable features, review minor bumps before enabling experimental ones. Digest problem types are now generated from the live apiguide.dev catalogue with unchanged type URIs, so this release is additive with no response-contract breakage.

Ask: Approve a scoped pilot (one service, stable features only) with a re-review at the next minor release.