Home

RestQL is an eloquent based data solver for your Laravel application. This package tries to adopt the good principles of GraphQL which they would allow its API clients to get only the data they need.

This package uses your settings as the input schema to determine the shape in which the data is resolved, in addition, follow the principles REST to assume the type of action to take on one or many resources of your API based on the HTTP verb of the request.

How it works

Unlike technologies like GraphQL, RestQL does not use pre-configured queries on the server side to query and return the data, instead the developer should only define the schema in package configuration where will establish a list of eloquent models that will be available on requests from customers.

How the data is treated depends on the relationships defined by the developer in each of its models, allowing deep queries between relationships and do eager loading of these automatically.

Similar to GraphQL, clients send queries in the body of the HTTP request using lifelong JSON notation. However, please note that the way these queries are built depends on the clauses and the custom resolvers allowed by your Laravel application.

For example, a client of your API needs a book list that includes the title of the book, the published_at and the author's name.

As you can imagine, these are separate entities so in a REST API Common would have to make two requests to the backend server to get this data. If you use RestQL you could re-factor your client's code in the following way.

import { get } from 'axios';

// You can explicitly define queries to use them
// elsewhere in your code.
const params = {
  books: {
    select: ['title', 'published_at'],
    with: {
      author: {
        select: 'name'
      }
    }
  }
};

get('https://laravel.app/api/restql', { params }).then(({ data: books }) => {
  console.log(books);
});

RestQL will interpret the HTTP GET method as a request for information, then it will take the body of this request and assume that each element of the first JSON level corresponds to a defined schema key, this should return an instance of the eloquent model of your application, in this case App\Book.

The next JSON level corresponds to the clauses that will be applied to the query builder of this model.

Basically the clauses represent the names of the methods of Illuminate\Database\Eloquent\Builder.

So the body sent in the petition would be interpreted with the following PHP code.

<?php

// Assuming that the parent model we want to obtain is the book's data.
// The variable $query represents the query constructor of the parent model,
// in this example, the App\Book model.
$query->select(['title', 'published_at'])->with([
    // In this case, the App\Book model has a method called "author"
    // which returns the data of the book's author.
    'author' => static function (Relation $relation) {
      $relation->select(['name']);
    }
  ]);

Finally we will have an eloquent query built based on a structure JSON fully optimized and returns only the data needed for the customers.

{
  "data": {
    "books": [
      {
        "title": "Eloquent JavaScript, Second Edition",
        "published_at": "2014-12-14T00:00:00.000Z",
        "author": {
          "name": "Marijn Haverbeke"
        }
      },
      {
        "title": "Learning JavaScript Design Patterns",
        "published_at": "2012-07-01T00:00:00.000Z",
        "author": {
          "name": "Addy Osmani"
        }
      },
      {
        "title": "Speaking JavaScript",
        "published_at": "2014-02-01T00:00:00.000Z",
        "author": {
          "name": "Axel Rauschmayer"
        }
      },
      // ...
    ]
  }
}