earthling-interactive/laravel-jsonapi

Friday, April 24, 2015
by jpchip
Repository
16 Watchers
1 Stars
152 Installations

PHP
0 Dependents
0 Suggesters
28 Forks
3 Open issues
35 Versions
0 % Grown

The README.md

JSON API helpers for Laravel 5

, _(*1)

Make it a breeze to create a jsonapi.org RC3 compliant API with Laravel 5., _(*2)

Code forked from echo-it/laravel-jsonapi project by Ronni Egeriis Persson., _(*3)

Installation

Add earthling-interactive/laravel-jsonapi to your composer.json dependency list, _(*4)
Run composer update., _(*5)

Requirements

PHP 5.4+
Laravel 5

Using laravel-jsonapi

This library is made with the concept of exposing models in mind, as found in the RESTful API approach., _(*6)

In few steps you can expose your models:, _(*7)

Create a route to direct the requests, _(*8)

In this example, we use a route for any OPTION requests, a generic route for interacting with resources, and another route for interacting with resource relationships:, _(*9)
```
Route::options('api/{model}/{id?}', 'ApiController@handleRequest');
Route::any('api/{model}/{id?}', 'ApiController@handleRequest');
Route::any('api/{model}/{id}/links/{relation}', 'ApiController@handleRequest');
```

Create your controller to handle the request, _(*10)

Your controller is responsible to handling input, instantiating a handler class and returning the response., _(*11)

     <?php namespace App\Http\Controllers;
    use EarthlingInteractive\JsonApi\Request as ApiRequest;
    use EarthlingInteractive\JsonApi\ErrorResponse as ApiErrorResponse;
    use EarthlingInteractive\JsonApi\Exception as ApiException;
    use Request;

    class ApiController extends Controller
    {
        public function handleRequest($modelName, $id = null, $relation = null)
        {
            /**
             * Create handler name from model name
             * @var string
             */
            $handlerClass = 'App\\Handlers\\' . ucfirst($modelName) . 'Handler';

            if (class_exists($handlerClass)) {
                $url = Request::url();
                $method = Request::method();
                $include = ($i = Request::input('include')) ? explode(',', $i) : [];
                $sort = ($i = Request::input('sort')) ? explode(',', $i) : [];
                $filter = ($i = Request::except('sort', 'include', 'page')) ? $i : [];
                $content = Request::getContent();

                $page = ($i = Request::input('page')) ? $i : [];
                if (!empty($page) && (!is_array($page) || empty($page['size']) || empty($page['number']))) {
                    return new ApiErrorResponse(400, 400, 'Expected page[size] and page[number]');
                }

                $request = new ApiRequest(Request::url(), $method, $id, $content, $include, $sort, $filter, $page, $relation);
                $handler = new $handlerClass($request);

                // A handler can throw EchoIt\JsonApi\Exception which must be gracefully handled to give proper response
                try {
                    $res = $handler->fulfillRequest();
                } catch (ApiException $e) {
                    return $e->response();
                }

                return $res->toJsonResponse();
            }

            // If a handler class does not exist for requested model, it is not considered to be exposed in the API
            return new ApiErrorResponse(404, 404, 'Entity not found');
        }
    }

Create a handler for your model, _(*12)

A handler is responsible for exposing a single model., _(*13)

In this example we have create a handler which supports the following requests:, _(*14)

GET /users (ie. handleGet function)
GET /users/[id] (ie. handleGet function)
PATCH /users/[id] (ie. handlePatch function)

Requests are automatically routed to appropriate handle functions., _(*15)

    <?php namespace App\Handlers;

      use Symfony\Component\HttpFoundation\Response;
      use App\Models\User;

      use EarthlingInteractive\JsonApi\Exception as ApiException;
      use EarthlingInteractive\JsonApi\Request as ApiRequest;
      use EarthlingInteractive\JsonApi\Handler as ApiHandler;
      use Request;

      /**
       * Handles API requests for Users.
       */
      class UsersHandler extends ApiHandler
      {
          const ERROR_SCOPE = 1024;

          /**
           * Handles GET requests. 
           * @param EarthlingInteractive\JsonApi\Request $request
           * @return EarthlingInteractive\JsonApi\Model|Illuminate\Support\Collection|EarthlingInteractive\JsonApi\Response|Illuminate\Pagination\LengthAwarePaginator
           */
          public function handleGet(ApiRequest $request)
          {
              //you can use the default GET functionality, or override with your own 
              return $this->handleGetDefault($request, new User);
          }

          /**
           * Handles PATCH requests. 
           * @param EarthlingInteractive\JsonApi\Request $request
           * @return EarthlingInteractive\JsonApi\Model|Illuminate\Support\Collection|EarthlingInteractive\JsonApi\Response
           */
          public function handlePatch(ApiRequest $request)
          {
              //you can use the default PATCH functionality, or override with your own
              return $this->handlePatchDefault($request, new User);
          }
      }

Note: Extend your models from EarthlingInteractive\JsonApi\Model rather than Eloquent to get the proper response for linked resources. In your model, you can define which relationships should be exposed:, _(*16)

    <?php namespace App\Models;

    use EarthlingInteractive\JsonApi\Model as ApiModel;

    class User extends ApiModel {

        public $exposedRelations = ['friends'];

        public function friends()
        {
            return $this->hasMany('App\Models\Friend');
        }
    }

Current features

According to jsonapi.org:, _(*17)

Resource Representations as resource objects
Resource Relationships
Relationship URLs e.g. /users/[id]/links/friends
Compound Documents
Sorting
Filtering (Note: Doesn't use FILTER keyword. An example: /users?name=Joe)
Pagination

The features in the Handler class are each in their own function (eg. handlePaginationRequest, handleSortRequest, etc.), so you can easily override them with your own behaviour if desired., _(*18)

Wishlist

Resource URLs
Updating Relationships
Sparse Fieldsets
Strict checking of application/vnd.api+json in content-type and Accept Headers

The Versions

24/04 2015

dev-master

9999999-dev

library laravel-jsonapi

earthling-interactive/laravel-jsonapi

The README.md

JSON API helpers for Laravel 5

Installation

Requirements

Using laravel-jsonapi

Current features

Wishlist

The Versions

dev-master

The Requires

The Development Requires

by Ronni Egeriis Persson

by Jared Chapiewsky

v6.0.2

The Requires

The Development Requires

by Ronni Egeriis Persson

by Jared Chapiewsky

5.x-dev

The Requires

The Development Requires

by Ronni Egeriis Persson

by Jared Chapiewsky

v5.0.2

The Requires

The Development Requires

by Ronni Egeriis Persson

by Jared Chapiewsky

v5.0.1

The Requires

The Development Requires

by Ronni Egeriis Persson

by Jared Chapiewsky

v6.0.1

The Requires

The Development Requires

by Ronni Egeriis Persson

by Jared Chapiewsky

v6.0.0

The Requires

The Development Requires

by Ronni Egeriis Persson

by Jared Chapiewsky

v5.0.0

The Requires

The Development Requires

by Ronni Egeriis Persson

by Jared Chapiewsky

v4.0.0

The Requires

The Development Requires

by Ronni Egeriis Persson

by Jared Chapiewsky

v3.1.3

The Requires

The Development Requires

by Ronni Egeriis Persson

by Jared Chapiewsky

v3.1.2

The Requires

The Development Requires

by Ronni Egeriis Persson

by Jared Chapiewsky

v3.1.1

The Requires

The Development Requires

by Ronni Egeriis Persson

by Jared Chapiewsky

v3.1.0

The Requires

The Development Requires

by Ronni Egeriis Persson

by Jared Chapiewsky

v3.0.1

The Requires

The Development Requires

by Ronni Egeriis Persson

by Jared Chapiewsky