Twill Api Laravel Package

Product Decisions This Supports

• Headless vs. monolithic delivery, cheaply. The single biggest decision this de-risks is "should we decouple the frontend?" Rather than a replatform, this package lets you prove the value of a content API against your existing Twill models in a spike measured in days. That converts a quarter-long architectural debate into a two-week experiment with a real client consuming real content.
• Build vs. buy on API plumbing. You will always build your domain resources; this package is the decision not to hand-roll JSON:API serialization, relationship inclusion, sparse fieldsets, and pagination semantics. Adopting it means your team spends its budget on content modeling and client experience instead of re-implementing a spec.
• Multi-channel roadmap sequencing. Once a read API exists, "mobile app," "partner feed," "marketing site rebuild," and "in-store kiosk" stop being separate engineering projects and become consumers of one contract. This supports prioritizing channels by reach rather than by backend cost.
• Which content types deserve exposure first. Because endpoints are per-model, you can ship a narrow surface (e.g., articles and case studies) and measure consumption before committing to exposing every entity. That is a roadmap decision backed by usage data, not opinion.
• Frontend framework independence. A JSON:API contract lets you choose Next.js, Nuxt, a native client, or an agency partner's stack without relitigating the CMS. Useful when the frontend team and CMS team are different vendors.
• Contract stability for external consumers. JSON:API compliance gives partners a documented, conventional query surface (include, fields[...], sort, pagination) instead of a bespoke API you'd have to document, version, and support yourself.
• Buying optionality on write paths. Choosing a read-only layer is itself a decision: it keeps content authoring in Twill's admin (where the editorial workflow, media handling, and permissions already are) and defers any "public submissions" requirement to a separate, small service. That's an architecture boundary worth making explicit early.

When to Consider This Package

Adopt when:

• Twill is already your CMS and you have Eloquent models using Twill traits (HasMedias, HasBlocks, HasSlug, etc.). The package is derivative value — it is worth approximately nothing without Twill, and considerable value with it.
• You need read-only delivery to one or more clients: a JS frontend, a mobile app, a partner, a static-site build pipeline.
• You want the JSON:API contract and are willing to keep clients spec-compliant rather than inventing a bespoke response shape.
• You have a small team that would rather extend a thin, Apache-2.0 base class than design serialization conventions from scratch.
• You can own the surrounding infrastructure — authentication/API keys, rate limiting, caching and CDN invalidation, and observability are not in scope here and must be planned for.

Look elsewhere, or budget for significant extension, when:

• You need write operations. This is read-only by design. Forms, submissions, user-generated content, and editorial actions via API are out of scope — plan a separate endpoint or service.
• You need GraphQL. Wrong tool; you'd be building a parallel layer.
• High-traffic public delivery is the goal. A per-request Laravel API is not a CDN. For large anonymous audiences you want a cached/static content layer in front, which changes the value proposition of this package considerably.
• You need fine-grained field-level authorization or multi-tenancy. Expect to write that yourself.
• The repository's maintenance signal matters to you. At ~14 stars and single-vendor stewardship, treat it as an internal accelerator with a fork-and-own contingency, not a strategic dependency. Pin versions; read the source before committing.
• Your data isn't in Twill, or your team has no Laravel depth.

How to Pitch It (Stakeholders)

For executives: We can offer a modern, decoupled content API to new frontends and channel partners without replatforming the CMS. This package is the thin, Apache-2.0-licensed adapter that exposes content we already manage in Twill, so the cost of testing a headless strategy drops from a quarter of engineering to roughly a sprint. It's low-commitment and reversible: if the experiment fails, we've lost a sprint, not an architecture.

For engineering: It's a read-only JSON:API layer over existing Twill models plus a base controller/resource structure for your own endpoints. It handles serialization, includes, sparse fieldsets, and pagination so you don't re-implement the spec. It does not handle auth, rate limiting, caching, or writes — those are ours to design, and we should scope them before the first external consumer ships. Maintenance risk is real given the low star count; we should pin the version, read the source, and be prepared to fork. Upside: small surface area, no vendor lock-in, and it composes with what we already have.

Recommendation: Run a two-week spike exposing one content type to one client, with API-key auth and a cache in front, and use the result to decide whether headless delivery becomes a roadmap commitment.