Download the PHP package bkstar123/laravel-api-buddy without Composer

laravel-api-buddy

This lightweight Laravel package provides a powerful and simple toolset for quickly building high-quality RESTful API web services for Eloquent model resources with several advanced features such as schema transformation as well as sorting, filtering, selecting and paginating. Using together with the Laravel Passport package, you can have a full-fledge API system ready to serve any clients in a matter of minutes.

Note:
– This is not a silver bullet to solve all API problems, for example: it does not support , queries. It does not “apifyies” your model resources out of the box, it is just your buddy to build a powerful API system as quickly as possible. There are many rooms for you to personalize your API design, laravel-api-buddy makes your journey easier, more comfortable and saves you from doing some boilerplate coding.

– Please visit https://github.com/bkstar123/api-demo for a detailed example about building API endpoints using bkstar123/laravel-api-buddy & Laravel Passport.

1 Requirements

It is recommended to install this package with PHP version 7.1.3+ and Laravel Framework version 5.6+

2 Installation

composer require bkstar123/laravel-api-buddy

It will also install ** as a dependency. You can visit https://github.com/barryvdh/laravel-cors for the detailed description of that package.

After installing, run:

It will copy all necessary configuration files to &

3 Configuration

is the config file of ** package, you should consult its documentation for the further details.

is the package's main config file, it contains the following options:

• ****: The maximum page size that a request can specify, by default it is 1000 items/page
• ****: The default page size that will be applied if a request does not specify, by default it is 10 items/page
• ****: Whether or not to replace the Laravel default exception handler with the one provided by the package. It is recommended to be set to (its default value) so that all exceptions can be converted to appropriate JSON responses
• ****: Whether or not to use transformation. It is recommmended to be set to (its default value) for the best security protection. Since the underlying PDO DB driver does not support binding column names, see https://laravel.com/docs/5.8/queries; the transformation should always be used whenever you allow user input to dictate the column names referenced by your queries.

4 Usage

Supposing that we need to build some API endpoints for resource.

4.1 General information

The package provides ** as the base API controller that can be extended by other API controllers. This has been automatically injected with an instance.

You can quickly scalfold an API controller with command. For example:

All API controllers extending have access to the property $apiResponser which holds an instance. The instance exposes the following methods:

• ****: is to return a collection of model resources in JSON with some features such as sorting, filtering, column selecting and paginating
• ****: is to return a model instance in JSON with column selecting capability
• ****: is to return a generic success JSON response
• ****: is to return a generic error JSOn response

Where:

• ****: is an instance of
  Example:

The following arguments are to be passed only in the case of using transformation:

• ****: fully qualified class name of the model API resource. See more about API Resources at https://laravel.com/docs/5.8/eloquent-resources
• ****: the fully qualified class name of the model transforming class, such as . The transforming class must extend and define the following property:
  +)

4.2 Without transformation

• Set option to in
• Run
• In app/Http/Controllers/UserController.php, assuming that returns a collection of user resources, returns an user instance and creates a new user instance

4.3 With transformation

Set option to in

a) Create API resource

The API resource will be created in directory, it extends

• The only required method for it to implement is ****, this method defines the way to transform the API response (server->client direction)

You can add more metadata to API response by using hook which accepts the mapping returned by as the only argument, enrich & return it, for example:

b) Create transformer
Run:

This class defines the mapping between the model's original columns and their transformed versions (mainly for the purpose of client->server direction)

c)

For some requests that modify the state of resource such as POST (creating new instance), PUT & PATCH (updating an existing instance), you will need to use middleware which are automatically registered with the Laravel IoC container by the package. This middleware only requires an argument which is the fully qualified name of the transform class (in the above example, it should be ), and it converts user inputs to their corresponding original database table column names & vice versa in case of validation errors.

4.4 CORS enabling

To enable CORS for all API endpoints, just register the middleware in 's 's key as follows:

This middleware is automatically register with Laravel IoC container by the package.

4.5 Consuming API

You can use the following queries to customize the API response:

a) Sorting

Sort the response data by col1 in the ascending order & col2 in the descending order

b) Selecting

Includes only col1 & col2 in the response data

c) Filtering

Filter the response data where and

The accepted operators: (defaults to )

d) Paginating

Paginating the response data with the page size of 10 items and get the page 6