Upgrading

From Version 0 to Version 1

Additions

• Improvements to the make:api-resource command - in particular, with regards to example routes.
• PUT implementation for Restful controller
  • Currently PUT assumes you will pass the UUID of the object in the URL, as is implied in the RFC

Improvements

• RestfulService has been streamlined and improved for the functionality it provides.
• Formatting of the meta array's key case to be consistent with API key case (for pagination endpoints for example)

Backwards incompatible improvements/features

In most cases there are wrappers created to make sure these changes won't break any existing functionality, but you should very much update accordingly anyway because anything deprecated will be removed in future versions.

Helpers

• Almost all helpers are no longer in the global namespace, have been moved to L5Api\Helpers
  • Old functions are still kept for backwards compatibility
• APIBoilerPlate::formatKeyCaseAccordingToReponseFormat has been renamed slightly to formatCaseAccordingToResponseFormat
  • A deprecated wrapper will exist for some time to help with this.

Model property $localWith split

The $localWith property was split into $itemWith and $collectionWith - to allow specifying a different set of relations to return with a GET / collection endpoint.

By default $collectionWith is null, and thus $itemWith will be used in all situations - however if $collectionWith is defined as an array of relations, then it will be used for getting a collection of a resource.

Policy Changes

• There is a new policy ability called viewAll which is checked for the getAll endpoint, which is used for the GET / (collection) requests. With this addition, it is important that this ability be added to the policies you have. The easiest way to deal with this change is just to add this function to your BasePolicy - which mimics previous functionality.

    public function viewAll(User $user)
    {
        return true;
    }

This was added to make the viewing of all resources of a model (as opposed to individual ones) more configurable at the resource/model policy level.

• RestfulChildController changes to $parentAbilitiesRequired array The view permission on a given resource has been changed from requiring own to view on the parent resource. This was deemed more sensible from a design point of view. Keep in mind, this array is entirely configurable at the controller class.

    public $parentAbilitiesRequired = [
        'view'      => 'view', // Previously 'own'
        ....

• Before function moved to boilerplate base from, from l5-api

This is a simple moving of functionality, designed to make it more clear and transparent that this logic exists. All you need to do for backwards compability, is add the following function to your BasePolicy.php class.

    /**
     * Process 'global' authorisation rules
     *
     * @param $user
     * @param $ability
     * @return bool
     */
    public function before(User $user, $ability)
    {
        if ($user->isAdmin()) {
            return true;
        }
    }

• Change the JSON formatter in the config/api.php file of your laravel application. This is to facilitate the metadata key casing improvements mentioned earlier.

    'formats' => [

        'json' => Specialtactics\L5Api\Http\Response\Format\Json::class,

    ],