- What is sycho/json-api and what problem does it solve?
- sycho/json-api is a PHP library for producing JSON:API-compliant documents from your application resources. It handles serialization, relationships, included resources, pagination links, metadata, and structured error objects so you do not hand-build the spec shape. It is a fork of neomerx/json-api maintained for the Flarum ecosystem, and it is framework-agnostic rather than Laravel-specific.
- Is sycho/json-api compatible with Laravel 11 and Laravel 12?
- There is no official Laravel integration package, so compatibility depends on your composer.json constraints and the PHP version the fork declares. The latest release dates to 2023, so it may not explicitly declare Laravel 11 or 12 support and could require constraint overrides. Integration is done by registering the encoder in a service provider and returning encoder-built responses from your controllers.
- How do I install sycho/json-api in a Laravel application?
- Install it with Composer using composer require sycho/json-api, then bind the encoder and any configuration you need in a service provider. You will also write a small response builder that satisfies Laravel's Responsable or JsonResponse contract, plus middleware for content negotiation and error rendering. The package is PSR-friendly and does not require native extensions.
- What is the difference between sycho/json-api and neomerx/json-api?
- sycho/json-api is a fork of the well-established neomerx/json-api, kept compatible for the Flarum ecosystem. The API surface is familiar to anyone who has used the parent library, which lowers discovery cost. Before adopting the fork, review the commit delta against upstream to see whether it is a thin patch, a rename, or a divergent rewrite.
- Do I need to write a schema class for every resource I expose?
- Yes, the package separates the encoder and decoder from schema definitions that you author per resource type. One schema class per exposed resource acts as a typed contract between your Eloquent models and the JSON:API wire format, and this is typically the bulk of the integration effort. That effort scales with your API surface, not with the package itself.
- How do I return included relationships and compound documents?
- You define relationship schemas alongside your resource schemas, and the encoder builds compound documents with included resources when the request asks for them. Your controllers pass the primary resource and the requested includes to the encoder, and it produces the top-level data, relationships, and included arrays in spec order. Eloquent models stay untouched; all shaping happens in the schema and encoder layer.
- Does sycho/json-api handle pagination links and metadata?
- Yes, it can generate pagination links, top-level links, and meta objects as part of the JSON:API document. You supply the pagination state and the library renders the standardized links rather than you assembling them manually in each controller. This keeps list endpoints consistent across resource types.
- How do I return JSON:API error objects from a Laravel controller?
- The package produces structured error objects that follow the JSON:API error format, including source pointers and detail fields. In Laravel you typically render these from an exception handler or dedicated middleware so validation, authorization, and not-found failures all return the same error document shape. You own the mapping from Laravel exceptions to those error objects.
- Does it support sparse fieldsets and content negotiation?
- The library implements the JSON:API 1.0 document model, including sparse fieldsets, relationships, and compound documents. Content negotiation and the application/vnd.api+json media type are handled at your HTTP boundary, usually via middleware you add around the encoder. The package itself does not provide routing, controllers, or query parsing.
- Is sycho/json-api actively maintained and safe for production?
- Adoption signals are weak: very few stars, no observable dependents, a single apparent maintainer, and a last release in April 2023. The main risks are fork divergence from neomerx/json-api, a compatibility ceiling with newer PHP and Laravel versions, and silent spec drift with no changelog. If you need JSON:API compliance specifically, evaluate upstream neomerx/json-api or a maintained alternative; if you only need an API shape, Laravel's native API Resources carry less third-party risk.