README

使用 Laravel 5 轻松创建一个符合 jsonapi.org RC3 规范的 API。

代码由 Ronni Egeriis Persson 从 echo-it/laravel-jsonapi 项目分支而来。

安装

1. 将 felipe-douradinho/laravel-jsonapi 添加到您的 composer.json 依赖列表中

2. 运行 composer update。

要求

• PHP 5.4+
• Laravel 5.1.*

使用 laravel-jsonapi

这个库是以暴露模型的概念为基础构建的，正如在 RESTful API 方法中找到的那样。

只需几个步骤即可暴露您的模型

1. 创建一个路由来引导请求

   在这个例子中，我们使用一个路由来处理任何 OPTION 请求，一个用于与资源交互的通用路由，以及另一个用于与资源关系交互的路由

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

2. 创建一个控制器来处理请求

   您的控制器负责处理输入、实例化处理类并返回响应。

   	 <?php namespace App\Http\Controllers;
   	use FelipeDouradinho\JsonApi\Request as ApiRequest;
   	use FelipeDouradinho\JsonApi\ErrorResponse as ApiErrorResponse;
   	use FelipeDouradinho\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');
   		}
   	}

3. 为您的模型创建一个处理程序

   处理程序负责暴露单个模型。

   在这个例子中，我们创建了一个支持以下请求的处理程序

   • GET /users (即 handleGet 函数)
   • GET /users/[id] (即 handleGet 函数)
   • PATCH /users/[id] (即 handlePatch 函数)

   请求会自动路由到相应的处理函数。

       <?php namespace App\Handlers;
     
         use Symfony\Component\HttpFoundation\Response;
         use App\Models\User;
         
         use FelipeDouradinho\JsonApi\Exception as ApiException;
         use FelipeDouradinho\JsonApi\Request as ApiRequest;
         use FelipeDouradinho\JsonApi\Handler as ApiHandler;
         use Request;
         
         /**
          * Handles API requests for Users.
          */
         class UsersHandler extends ApiHandler
         {
             const ERROR_SCOPE = 1024;
             
             /**
              * Handles GET requests. 
              * @param FelipeDouradinho\JsonApi\Request $request
              * @return FelipeDouradinho\JsonApi\Model|Illuminate\Support\Collection|FelipeDouradinho\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 FelipeDouradinho\JsonApi\Request $request
              * @return FelipeDouradinho\JsonApi\Model|Illuminate\Support\Collection|FelipeDouradinho\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);
             }
         }

注意：从 FelipeDouradinho\JsonApi\Model 扩展您的模型而不是从 Eloquent，以获得对链接资源的适当响应。在您的模型中，您可以定义哪些关系应该被暴露

	<?php namespace App\Models;

	use FelipeDouradinho\JsonApi\Model as ApiModel;
	
	class User extends ApiModel {
		
		public $exposedRelations = ['friends'];
	
		public function friends()
		{
		    return $this->hasMany('App\Models\Friend');
		}
	}

当前功能

根据 jsonapi.org

• 资源表示 作为资源对象
• 资源关系
• 关系 URL 例如 /users/[id]/links/friends
• 复合文档
• 排序
• 过滤（注意：不使用 FILTER 关键字。例如：/users?name=Joe）
• 分页

处理程序类中的功能各自在其自己的函数中（例如，handlePaginationRequest、handleSortRequest 等），因此您可以轻松地根据自己的行为覆盖它们。

愿望清单

• 资源 URL
• 更新关系
• 稀疏字段集
• 严格检查 content-type 和 Accept 头中的 application/vnd.api+json