Skip to content
MundoProgra JSON:API
Menu

Start

Home

It turns a Laravel API into an end-to-end JSON:API 1.1 service: it accepts and validates requests in the standard and responds in the standard, for both success and error responses.

Status: version 0.1.0, under validation. The API described here is complete, covered by tests on Laravel 10 to 13 and tried in a real application. In 0.x the API may change between minor versions (with ^0.1 Composer installs only 0.1.x).

Installation → One command and you are done: the package is auto-discovered. Getting started → A resource, a controller and its routes, from start to finish. Errors → Every code and the order in which they are checked. Configuration → Every option, its environment variable and its default.

What is JSON:API

JSON:API is a specification, not a library: an agreement on how a server and a client exchange data as JSON over HTTP. It defines the shape of responses, of the requests that create or change data, of the relationships between resources, of the query parameters and of the errors. The full text is at jsonapi.org/format.

Because every API that follows it speaks the same way, a client or a library written for one works with another, and the team no longer has to argue about how to name fields, how to paginate or how to return an error.

Its main ideas:

  • Resources: everything the API exposes is an object with a type and an id, and its data goes inside attributes.
  • Relationships: a resource points to others by their type and id, inside relationships. With include they can come in the same response, in included and without repeating.
  • Queries with fixed names: include to bring relationships, fields[type] to ask for only some fields and sort to order; page and filter are reserved for pagination and filtering.
  • Uniform errors: always an errors array with the status, a code and a source that points to the field or parameter that failed.
  • Its own content type: application/vnd.api+json, in both Accept and Content-Type.

This is what a response with an article and its author looks like:

{
  "jsonapi": { "version": "1.1" },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": { "title": "Hello, JSON:API" },
    "relationships": {
      "author": { "data": { "type": "people", "id": "9" } }
    },
    "links": { "self": "/articles/1" }
  },
  "included": [
    { "type": "people", "id": "9", "attributes": { "name": "Ada" } }
  ]
}

What this package does

  • Responds in JSON:API: resources, paginated collections, relationships, included, links and meta, and every error (validation, 401, 404, 405 and 500 included) as an error document with source.pointer or source.parameter.
  • Validates what arrives: the headers (Accept and Content-Type), the query parameters (include, fields, sort, filter, page) and the body document, with the exact pointer of the failing member.
  • Applies the query to Eloquent with whitelists you write: filters, sorting, pagination and eager loading of relationships.
  • Registers no routes or controllers: you decide the URLs and the logic; the package takes care of the format.
  • Switches itself on on install, without touching bootstrap/app.php, Kernel or Handler.

Requirements

  • PHP 8.1 or higher
  • Laravel 10, 11, 12 or 13