[TOC]
Begin by installing this package through Composer.
You can run:
composer require paulvl/json-api
Or edit your project's composer.json file to require paulvl/json-api.
"require-dev": {
"paulvl/json-api": "dev-master"
}
Next, update Composer from the Terminal:
composer update --dev
Once the package's installation completes, the final step is to add the service provider. Open config/app.php, and add a new item to the providers array:
PaulVL\JsonApi\JsonApiServiceProvider::class,
Finally publish package's configuration file:
php artisan vendor:publish
Then the file config/json-api.php will be created.
That's it! You're all set to go. Run the artisan command from the Terminal to see the new json-api commands.
php artisan
To fast deploy your RESTful JsonApi server you have to use PaulVL\JsonApi\Model and PaulVL\JsonApi\Controller classes.
Begin creating a model using json-api:make-model command. For example:
php artisan json-api:make-model Models\MyModel
This will create the Models/MyModel.php file that will look like this:
<?php
namespace App\Models;
use PaulVL\JsonApi\Model;
class MyModel extends Model
{
/**
* The attributes that are mass assignable.
*
* @var array
*/
protected $fillable = [];
/**
* The attributes excluded from queries and the model's JSON form.
*
* @var array
*/
protected $hidden = [];
/**
* The relationship included on the model's JSON form.
*
* @var array
*/
protected $displayable_relations = [
//'relation_example'
];
/**
* Validation rules. If any field needs unique validation, add this rule at the end of the line like example
*
* @var array
*/
static protected $rules = [
//'field_example' => 'required|email|max:255|unique:table,column'
];
/*
public function relation_example() {
return $this->belongsTo('Class', 'foreign_key', 'primary_key');
}
*/
}
As we can see there are two new attributes, displayable_relations and rules.
The displayable_relations attribute will load all named relations to the json-api result, for example:
If we define relation_example funcion as above:
...
public function relation_example() {
return $this->belongsTo('Class', 'foreign_key', 'primary_key');
}
...
And then add the relation name to the displayable_relations array:
...
protected $displayable_relations = [
'relation_example'
];
...
this will produce a json-api result response that will look like this:
{
"data": [
{
"type": "mymodel",
"id": 1,
"attributes": [
"name": "name",
"class_id": 1,
"created_at": "2015-01-01 00:00:00",
"updated_at": "2015-01-01 00:00:00"
],
"relationships": {
"relation_example": {
"data": {
"type": "class",
"id": 1
}
}
}
}
],
"meta": {
"copyright": "Copyright 2015 Your Business App.",
"authors": [
"Paul Vidal"
]
},
"jsonapi": {
"version": "1.0"
}
}
Now you can specify validation rules inside model itself, just add the validation rultes to the rules array:
...
static protected $rules = [
'field_example' => 'required|email|max:255|unique:table,column'
];
...
Note: if one field need to have a unique validation rule, that must be specified at the end, this because update rules will be generate automatically and add the corresponding exception rules. To get update rules use
getUpdateRulesfunction:
$update_rules = $mymodel_instance->getUpdateRules();
Continue creating a controller using json-api:make-controller command. For example:
php artisan json-api:make-controller MyController
This will create the Http/Controllers/MyController.php file that will look like this:
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use PaulVL\JsonApi\Controller as JsonApiController;
use PaulVL\JsonApi\Response;
class MyController extends JsonApiController
{
/**
* Sets the model class that will be handled by this class.
* @var string
*/
protected $model_class = '';
/**
* saveData functions allows you to manual handle save actions triggered from store function on.
* Uncomment this method only if you want to manual handle save actions.
*
* @param array $inputs There are the request's inputs inyected from store function.
* @return PaulVL\JsonApi\response returns response according to action.
*/
/*
public function saveData(array $inputs) {
try {
$response = new Response;
// handle inputs and create and $object and store it.
$response->handleData($object); // You should pass an object to response's handleData method.
return $response->responseCreated(); // You must return a responseCreated.
} catch (Exception $e) { // If any error is fired always return a responseInternalServerError.
$response = new Response;
return $response->responseInternalServerError();
}
}
*/
/**
* updateData functions allows you to manual handle update actions triggered from update function on .
* Uncomment this method only if you want to manual handle update actions.
*
* @param [type] $object Object inyected from update function.
* @param array $inputs There are the request's inputs inyected from store function.
* @return PaulVL\JsonApi\response returns response according to action.
*/
/*
public function updateData($object, array $inputs) {
try {
$response = new Response;
// handle inputs and update the $object.
$response->handleData($user); // You should pass the updated object to response's handleData method.
return $response->response(); // You must return a responseOk or just response.
} catch (Exception $e) { // If any error is fired always return a responseInternalServerError.
$response = new Response;
return $response->responseInternalServerError();
}
}
*/
/**
* arrangeInputs functions allows you to manual handle inputs before validation.
* Uncomment this method only if you want to manual arrange inputs.
*
* @param array $inputs There are the request's inputs inyected from store function.
* @return array $inputs.
*/
/*
public function arrangeInputs(array $inputs) {
// arrange inputs.
return $inputs;
}
*/
/**
* Only if you need to implement create and edit function
* you can override them. They return error 404 as default.
*/
// public function create() { }
// public function edit($id) { }
}
As you can see there are many configurable things on the controller, but the most important is the model_class attribute, there you have to sets the model class name that will be handled by this controller, for example:
...
protected $model_class = 'App\Models\MyModel';
...
This means that our MyController will handle MyModel.
Finally once that we have already created our MyController controller and MyModel model classes, we just need to add the resource route to access our controller on Http/routes.php file, like this:
Route::resource('my-model', 'MyController', ['except' => ['create', 'edit']]);
JsonApi provides a simple way to paginate your results just add the "paginate" and "page" (optional) parameters to the url, for example:
http://example.com/api/user?paginate={items_per_page}&page={current_page}
Note:
- If there are no page parameter, pagination will be set on the first page.
- If page parameter is set with an unexisting value, JsonApi's will return an Ok response with empty data.
JsonApi provides a fast way to running database queries. It can be used to perform most database operations in your application through URL requests, and works on all database systems supported by Laravel.
To run a query just add a q parameter to the url, and the content of this parameter must have this form "{clause}={argument_1},...,{argument_n}"
http://example.com/api/user?q={clause}={argument_1},...,{argument_n}
Note: To chain clauses just add a pipe | between clauses. for example:
http://example.com/api/user?q=clause1=arg1,arg2,arg3|clause2=arg1,arg2,arg3
The most basic call to where requires three arguments. The first argument is the name of the column. The second argument is an operator, which can be any of the database's supported operators. The third argument is the value to evaluate against the column.
For example, here is a query that verifies the value of the "votes" column is equal to 100:
http://example.com/api/user?q=where=votes,=,100
For convenience, if you simply want to verify that a column is equal to a given value, you may pass the value directly as the second argument to the where clause:
http://example.com/api/user?q=where=votes,100
You can also verify that a column is equal to a given value adding both values as url parameters:
http://example.com/api/user?votes=100
Note: this will only work for
whereclauses, also you can chain them all:http://example.com/api/user?votes=100&name=Pepe
You may chain where constraints together, as well as add or clauses to the query. The orWhere method accepts the same arguments as the where clause:
http://example.com/api/user?q=where=votes,>,100|orWhere=name,Pepe
The whereBetween clause verifies that a column's value is between two values:
http://example.com/api/user?q=whereBetween=votes,10,100
The whereNotBetween clause verifies that a column's value lies outside of two values:
http://example.com/api/user?q=whereNotBetween=votes,10,100
The whereIn clauseverifies that a given column's value is contained within the given array:
http://example.com/api/user?q=whereIn =votes,10,100
The whereNotIn clauseverifies that the given column's value is not contained in the given array:
http://example.com/api/user?q=whereNotIn=votes,10,100
The whereNull clause verifies that the value of the given column is NULL:
http://example.com/api/user?q=whereNull =updated_at
The whereNotNull clause verifies that the column's value is not NULL:
http://example.com/api/user?q=whereNotNull=updated_at
The orderBy clause allows you to sort the result of the query by a given column. The first argument to the orderBy clause should be the column you wish to sort by, while the second argument controls the direction of the sort and may be either asc or desc:
http://example.com/api/user?q=orderBy=created_at,desc