Skip to content

Latest commit

 

History

History
163 lines (116 loc) · 4.89 KB

README.md

File metadata and controls

163 lines (116 loc) · 4.89 KB
Raw

JSON API helpers for Laravel 4

Make it a breeze to create a jsonapi.org compliant API with Laravel 4.

Installation

Add echo-it/laravel-jsonapi to your composer.json dependency list and run composer update.

Requirements

  • PHP 5.4+
  • Laravel 4 (Tested with 4.2)

Using laravel-jsonapi

This library is made with the concept of exposing models in mind, as found in the RESTful API approach.

In few steps you can expose your models:

  1. Create a route to direct the requests

    In this example, we use a generic route for all models and HTTP methods:

    Route::any('{model}/{id?}', 'ApiController@handleRequest');

  2. Create your controller to handle the request

    Your controller is responsible to handling input, instantiating a handler class and returning the response.

    <?php

use EchoIt\JsonApi\Request as ApiRequest;
use EchoIt\JsonApi\ErrorResponse as ApiErrorResponse;
use EchoIt\JsonApi\Exception as ApiException;

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

        if (class_exists($handlerClass)) {
            $method = Request::getMethod();
            $include = ($i = Input::get('include')) ? explode(',', $i) : $i;

            $request = new ApiRequest($method, $id, $include);
            $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(str_plural($modelName));
        }

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

  3. Create a handler for your model

    A handler is responsible for exposing a single model.

    In this example we have create a handler which supports the following requests:

    • GET /users
    • GET /users/[id]
    • PUT /users/[id]
    <?php

use Symfony\Component\HttpFoundation\Response;

class UsersHandler extends EchoIt\JsonApi\Handler
{
    const ERROR_SCOPE = 1024;

    protected static $exposedRelations = ['friends'];

    public function handleGet(EchoIt\JsonApi\Request $request)
    {
        if (empty($request->id)) {
            return $this->handleGetAll($request);
        }

        return \User::find($request->id);
    }

    protected function handleGetAll(EchoIt\JsonApi\Request $request)
    {
        return \User::all();
    }

    public function handlePut(EchoIt\JsonApi\Request $request)
    {
        if (empty($request->id)) {
            throw new EchoIt\JsonApi\Exception(
                'No ID provided',
                static::ERROR_SCOPE | static::ERROR_NO_ID,
                Response::HTTP_BAD_REQUEST
            );
        }

        $updates = \Input::json('users');
        $user = \User::find($request->id);

        if (is_null($user)) return null;

        $user->fill($updates);

        if ( ! $user->save()) {
            throw new EchoIt\JsonApi\Exception(
                'An unknown error occured',
                static::ERROR_SCOPE | static::ERROR_UNKNOWN,
                Response::HTTP_INTERNAL_SERVER_ERROR
            );
        }

        return $user;
    }
}

    Note: Extend your model from EchoIt\JsonApi\Model rather than Eloquent to get the proper response for linked resources.

Current features

According to jsonapi.org:

Wishlist