Download the PHP package trivolink/unified-api without Composer
On this page you can find all versions of the php package trivolink/unified-api. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download trivolink/unified-api
More information about trivolink/unified-api
Files in trivolink/unified-api
Package unified-api
Short Description Unified JSON API contract for Inertia-powered Laravel backends — serve web, mobile and desktop clients from one set of routes.
License MIT
Homepage https://github.com/trivolink/unified-api
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package unified-api
trivolink/unified-api
One Laravel backend, three clients. Web keeps Inertia SSR HTML (SPA + SEO); mobile and desktop apps receive a standardized JSON envelope — from the same URLs and the same controllers.
New here and deciding? Read docs/ANALYSIS.md — the problem, the alternatives compared, honest trade-offs, and when this package is the wrong tool.
Response matrix
| Request | Response |
|---|---|
Accept: text/html |
Inertia SSR HTML (unchanged) |
X-Inertia: true |
Inertia page object (unchanged SPA navigation) |
Accept: application/json |
Envelope: {data, meta, message, version} |
data— fully resolved page props (shared + page props, eager: deferred/optional props included)meta—component(screen hint) andurl, each disableable viaunified-api.meta.*; always a JSON object, never an arraymessage— flashedmessagekey when present, elsenullversion— API contract version (UNIFIED_API_VERSION, defaultv1)
POST endpoints that redirect respond 200 (configurable) with
meta.redirect instead of a 302/303, so native clients never silently
follow redirects. Validation and HTTP errors keep their status code and
arrive wrapped: {data: null, message, errors?, version} — including
exception-rendered responses (401 unauthenticated, 404, validation 422,
throttle 429, server 5xx).
Install
Publish config (optional):
Auth: Sanctum dual-mode
Swap the auth middleware on your shared (web) route group:
Sanctum's guard checks Authorization: Bearer <token> first (issue
personal access tokens to your mobile/desktop apps) and falls back to
the web session for browsers — your existing Fortify/session flow keeps
working untouched.
Getting a first token: POST /api/token
Mobile/desktop clients bootstrap their bearer token with an email + password exchange (stateless, throttled to 5/min by default):
Wrong credentials get the 422 envelope with errors.email. The route
requires the user model to use Laravel\Sanctum\HasApiTokens and can be
configured or disabled under unified-api.token_endpoint:
CSRF
Browser POSTs still require CSRF tokens (Inertia sends them
automatically). Stateless JSON clients must not be blocked by CSRF, so
swap the framework middleware in bootstrap/app.php:
This is CSRF-safe: the exemption requires the custom
Accept: application/json header, which cross-site forms can never set
and cross-origin fetches cannot send without passing a CORS preflight.
Bearer-authenticated requests carry no ambient cookie credentials for an
attacker to ride.
Mobile/Desktop client checklist
- Send
Accept: application/jsonon every request. - Bootstrap:
POST /api/tokenwith email + password, storedata.token. - Authenticate every request with
Authorization: Bearer <token>. - Read
version; when it differs from your compiled-in contract (e.g. you shippedv1, server now sendsv2), prompt the user to update. - On
meta.redirect, navigate explicitly — do not rely on HTTP redirect following.
Why not just send X-Inertia from mobile?
The Inertia page object is a UI protocol, not an API contract:
component names refer to React/Vue page components the native app
does not have, url/version exist for browser history and asset
hashing, and partial-reload/deferred/merge semantics assume the Inertia
JS client. The envelope is a stable, minimal contract purpose-built for
native consumers.
Testing your app
Everything Inertia offers keeps working (assertInertia etc.). For
unified clients, assert on the envelope:
Contract testing
The envelope's data is your resolved page props — for native clients,
those props ARE the API. Freeze their shape with snapshot tests so a
web refactor that renames, retypes or drops a prop fails CI instead of
silently breaking shipped apps:
The first run writes tests/Snapshots/UnifiedApi/dashboard.json (shape
only — key tree plus JSON types; values never recorded, so factory data
and timestamps cannot flake). Later runs compare. Non-2xx responses fail
immediately: error envelopes are not contracts.
When a snapshot diff appears in a PR, the change rule is two lines:
- additive (new keys only) — regenerate:
ENVELOPE_SNAPSHOT_UPDATE=1 vendor/bin/pest - breaking (remove/rename/retype) — bump
UNIFIED_API_VERSION, update consumers, and regenerate in the same commit
Store the snapshot path override for unusual layouts with
EnvelopeSnapshot::usingSnapshotPath(...); the default is
base_path('tests/Snapshots/UnifiedApi').
