Laravel Rest Laravel Package

Getting Started

This release changes nothing at runtime — it is verification, docs and metadata only — so 1.6.0 → 1.6.1 is a safe patch bump. What it does give you is the single most useful artifact for evaluating the package: a public, reproducible coverage matrix of 62 real APIs, so you can stop guessing whether it fits your target API.

1. Install and publish config as per the README, then pin ^1.6 (no breaking changes in this release).
2. Look here first: docs/live-verification.md. Do not start with the README feature list — start with the matrix. Find an API whose shape matches yours (pagination style + response envelope + detail path), not one whose topic matches.
3. Then read docs/capabilities.md. This is the list of real-world shapes the package cannot express. Skim it before you commit to the package for a given integration; it is the difference between a one-hour job and a two-day fight.
4. First use case: a read-only, paginated, envelope-wrapped list endpoint (data / results / hydra:member) mapped to one model, then find($id) against a standard {endpoint}/{id} detail path. That combination is the package's happy path and is confirmed on many APIs in the catalog.

Clone the matrix API's config, not a blank config. The catalog is effectively a library of worked examples for every envelope and pagination style the package supports.

Implementation Patterns

Shape-match, don't topic-match. Before writing any config, classify your target API on three axes: pagination (page / offset / cursor), envelope (bare array, data, results, hydra:member, JSON:API, GraphQL, JSON-RPC), and detail path ({endpoint}/{id} or not). Two of three matching is usually a config job; failing detail path is a design problem (see Gotchas).

One model per endpoint, envelope in config. Keep response unwrapping declarative at the connection/model level rather than post-processing in your application code. The catalog demonstrates that the same package handles JSON:API and JSON-RPC as configuration, so hardcoding a $response['data'] unwrap in a service class is a smell.

Treat the unsupported list as your integration checklist. Each documented limitation reproduces on several APIs and is asserted by the suite — meaning it is real and current, not a stale caveat. Walk capabilities.md against your target API before estimating. If your API puts totals in headers or uses repeated query params for membership filters, you already know those calls need a different tool.

Keep a small real-API smoke suite, separate from unit tests. The nightly live-verification workflow is the pattern worth copying: real third-party calls in their own suite, with pass / fail / skip / unsupported semantics. Note that skip exists because a timeout or 429 is not a defect — build the same distinction into your own smoke tests so a flaky vendor doesn't page you.

Do not put the live commands in your CI. composer live:catalog && composer live:report hits 62 public APIs and will be rate-limited or flaky. Run it locally when you upgrade the package, or when a vendor changes their response shape.

Escape hatch for unsupported shapes. For repeated query params, header totals, or non-standard detail paths, use Laravel's HTTP client directly for those specific calls and keep the package for the endpoints it models well. Mixing is fine; forcing the package to cover a shape it has documented as out of scope is not.

Gotchas and Tips

• Positional-array rows crash with a raw TypeError. If an API returns rows as arrays rather than objects ([["abc123", "United States", ...]]), integer keys reach Model::fill() and isFillable(string $key) throws — on a perfectly valid HTTP 200. Affects OpenSky's states and Dog CEO's breed map today. Mitigate by mapping positional rows to associative arrays before fill (array_combine against a known column list), and don't expect a typed package exception. Tracked for 1.7.
• No pagination totals if the API sends them in headers. total()-style introspection won't be available. Design UIs around "load more" rather than "page 3 of 47".
• Errors inside HTTP 200 are not surfaced. Several real APIs return error bodies with a 200 status; the package cannot express this, so add your own validation on the decoded payload for those integrations.
• Detail paths are hardcoded to {endpoint}/{id}. Non-standard detail routes (/users/{id}/profile, /items/by-slug/{slug}) need a separate model or the raw HTTP client.
• Bring your own retry/backoff. The package's own suite treats 429 and timeouts as environmental skips; that tolerance lives in the verification harness, not in your app. Configure retry() on the underlying client for production.
• Cursor, offset and page are not interchangeable. Don't assume perPage translates across styles; cursor APIs frequently ignore page numbers entirely, and the catalog reflects that.
• Trust the docs over third-party write-ups. The unsupported entries are asserted to stop reproducing and fail the suite when they do — this documentation is tested against reality and will not quietly rot. Conversely, don't assume an unlisted capability works; the matrix is the claim being made.
• Debug order: (1) is my API's shape in the matrix? (2) does my envelope config match? (3) is my detail path standard? Most "package is broken" reports resolve at step 1 or 2 — a shape mismatch, not a defect.
• Upgrading: 1.6.1 carries no runtime changes, so it is a zero-risk bump. Watch for 1.7 specifically for the fill() type fix and any items promoted out of ROADMAP.md.