, (*1)
🚨 THIS PACKAGE HAS BEEN ABANDONED 🚨, (*2)
We don't use this package anymore in our own projects and there are many, better alternatives, so that's why we have chosen to abandon it. We suggest using laravel-json-api/laravel or one of the other alternatives instead. Feel free to fork our code and maintain your own copy., (*3)
Laravel JSON API server
Set up a laravel API in just a few minutes with this package. All the standard API functionality is already there for you., (*4)
This package strives to save you some time while building your API.
It already has the basic features an API should have, like:, (*5)
- Generators to generate your needed files for each model
- An abstract layer to handle your basic CRUD actions
- Creates routes for all your endpoints
- Support for a few useful URL parameters
- Permission and route permission handling
- Responses in json api format (http://jsonapi.org/)
- Automatically translates your models based on your database
Install
Via Composer, (*6)
$ composer require swisnl/json-api-server
Sample
Please see the folder sample for a sample of an application using this package., (*7)
Usage
Base Api Classes
There are a few base classes your classes should/could inherit:, (*8)
BaseApiController
This controller handles your basic CRUD actions as well as permissions if you choose to use permissions., (*9)
BaseApiRepository
This repository is a standard base repository with a small addition that it figures out your models relationships., (*10)
If you want to use your own BaseRepository, you have to implement the RepositoryInterface. This ensures that you have full compatibility with the BaseApiController., (*11)
The BaseApiRepository uses a trait to retrieve a models relationships. You can use this trait if you want to use the existing implementation., (*12)
Generating the required files
After installing the package you can instantly generate all the required files by executing this command:, (*13)
$ php artisan json-api-server:generate-all {Model}
To override the default path without overriding the laravel_generator config file, you can use the --path={path} option. For example:, (*14)
$ php artisan json-api-server:generate-all Test --path=app/temp/
This generates the following files:, (*15)
- An eloquent model
- A translation model
- An API controller
- Should extend the BaseApiController
- A routes file where the all the CRUD endpoints are defined
- A repository for your model
- Could extend the BaseApiRepository
- A policy for checking permissions
- 1 test for checking if a user has permissions for the endpoint
You'll be able to do the basic CRUD actions without writing anything., (*16)
You also have the ability to generate the files separately:, (*17)
$ php artisan json-api-server:generate-controller {name}
$ php artisan json-api-server:generate-model {name}
$ php artisan json-api-server:generate-model-permissions {name}
$ php artisan json-api-server:generate-policy {name}
$ php artisan json-api-server:generate-repository {name}
$ php artisan json-api-server:generate-routes {name}
$ php artisan json-api-server:generate-test {name}
$ php artisan json-api-server:generate-translation {name}
Configuration
If you would like to override the configuration files., (*18)
$ php artisan vendor:publish --tag=laravel-api
$ php artisan vendor:publish --tag=laravel-api-templates
If you decide to override the templates, make sure you override the laravel api config too. You have to define where your own templates are in the config., (*19)
This is the default configuration:, (*20)
return [
// Generator configuration
'path' => [
'model' => app_path('/'),
'model_permissions' => app_path('Permissions/'),
'translation' => app_path('Translations/'),
'controller' => app_path('Http/Controllers/Api/'),
'repository' => app_path('Repositories/'),
'policy' => app_path('Policies/'),
'auth_test' => base_path('tests/Authentication/'),
'templates' => 'vendor/swisnl/laravel-api/resources/templates/',
'routes' => app_path('Http/Routes/')
],
'namespace' => [
'model' => 'App',
'model_permissions' => 'App\Permissions',
'controller' => 'App\Http\Controllers\Api',
'repository' => 'App\Repositories',
'translation' => 'App\Translations',
'policy' => 'App\Policies',
'auth_test' => 'App\Tests\Authentication'
],
// Permissions configuration
'permissions' => [
'checkDefaultIndexPermission' => false,
'checkDefaultShowPermission' => false,
'checkDefaultCreatePermission' => false,
'checkDefaultUpdatePermission' => false,
'checkDefaultDeletePermission' => false,
],
// Load all relationships to have response exactly like json api. This slows down the API immensely.
'loadAllJsonApiRelationships' => true,
];
Requests and responses
All requests and responses are formatted according to the format specified by http://jsonapi.org/., (*21)
There are several respond methods at your disposal in your controller. The following respond methods are implemented at this moment:, (*22)
return $this->respondWithOk($object);
return $this->respondWithPartialContent($object);
return $this->respondWithCreated($object);
return $this->respondWithNoContent($object);
return $this->respondWithCollection($object);
These methods automatically converts your objects to json api format and creates a response with the correct status code and body., (*23)
Using policies
If you decide to use policies to check for the user's pemissions you have to add the policies to your Providers\AuthServiceProvider., (*24)
protected $policies = [
Sample::class => SamplePolicy::class,
];
public function boot()
{
$this->registerPolicies();
}
The policies are preconfigured to work with Laravel passport, if you want to use another form of authorizing actions you can change the methods., (*25)
If you want to redirect the validation to a specific function in your policy., (*26)
$this->authorizeAction('show');
If you want to check if they can request a specific object you can add that object as the second parameter:, (*27)
$this->authorizeAction('show', $requestedObject);
URL parameters out of the box
The following URL parameters are supported after installing this package:, (*28)
- ?include={relationship}: To add all relationship data to the response.
- ?page={pageNumber}: To decide which page the pagination should show.
- ?per_page={amountToShowPerPage}:To decide how many items you get per page.
- ?ids={commaSeperatedIds}: To retrieve a collection of objects belonging to the ids.
- ?exclude_ids={commaSeperatedIds}: To retrieve a collection of objects not belonging to the ids.
- ?lang={language}: (Requires the configure-locale middleware) to change the php locale to the desired language and automatically translates all translatable models.
- ?fields={columns}: To retrieve certain columns.
- ?order_by_desc={column}: To order descending based on a column.
- ?order_by_asc={column}: To order ascending based on a column.
Mandatory middleware
- inspect_content_type: Required. It ensures that the requests should be in json format. If it's in another format it throws a ContentTypeNotSupportedException.
Optional middleware
There is optional middleware:, (*29)
- configure-locale: used to configure the language for translating your responses. Also configurable by using the URL paramater ?lang={language}
Passport installation
Note: if you want to know more about laravel passport and why these commands should be run go to https://laravel.com/docs/passport, (*30)
$ composer require laravel/passport
$ php artisan migrate
$ php artisan passport:install
After running this command, add the Laravel\Passport\HasApiTokens trait to your App\User model, (*31)
Next, you should call the Passport::routes method within the boot method of your AuthServiceProvider., (*32)
Finally, in your config/auth.php configuration file, you should set the driver option of the api authentication guard to passport. This will instruct your application to use Passport's TokenGuard when authenticating incoming API requests., (*33)
If you created your own routes make sure you have the auth:api middlware on all the routes you want to use passport with., (*34)
Packages Laravel-Api uses
Laravel framework
- https://laravel.com/docs/
Astrotomic / laravel-translatable
- https://github.com/Astrotomic/laravel-translatable
Change log
Please see CHANGELOG for more information on what has changed recently., (*35)
Contributing
Please see CONTRIBUTING and CODE_OF_CONDUCT for details., (*36)
Security
If you discover any security related issues, please email security@swis.nl instead of using the issue tracker., (*37)
Credits
License
The MIT License (MIT). Please see License File for more information., (*38)
SWIS
SWIS is a web agency from Leiden, the Netherlands. We love working with open source software., (*39)
Wallogit.com
