Laravel Framework REST API
Пакет разработан для удобства работы с API запросами. На данный момент этот модуль предоставляет всего лишь
контроллер, с набором методов, которые помогут организовать работу с AJAX запросами., (*1)
Установка
composer require kodicms/laravel-api
Добавить фасад в алиасы
'RouteAPI' => KodiCMS\API\RouteApiFacade::class,
Внести изменения в файл app\Exceptions\Handler.php
...
use KodiCMS\API\Http\Response as APIResponse;
use KodiCMS\API\Exceptions\Exception as APIException;
...
/**
* Render an exception into an HTTP response.
*
* @param \Illuminate\Http\Request $request
* @param \Exception $e
*
* @return \Illuminate\Http\Response
*/
public function render($request, \Exception $e)
{
if ($request->ajax() OR ($e instanceof APIException)) {
return (new APIResponse(config('app.debug')))
->createExceptionResponse($e);
}
...
}
Описание
Контроллер
Контроллер необходимо наследовать от KodiCMS\API\Http\Controllers\Controller, после чего он начнет возвращать
все ответы (ошибки и т.д.) в определенном формате с возможностью выбора типа ответа (json, xml, yaml):, (*2)
Пример ответа:, (*3)
{
code: 200,
content: '....',
type: 'content',
method: '...'
}
Коды ответов:, (*4)
-
200 - ok
-
110 - не передан обязательный параметр в запросе
-
120 - ошибка валидации
-
130 - неизвестная ошибка
-
140 - ошибка токена
-
150 - попытка в модели установить значение защищенного поля
-
220 - ошибка прав доступа
-
403 - неавторизован
-
404 - страница не найдена
Тип ответа, (*5)
-
error - ошибка
-
content - ответ
-
redirect - редирект
Пример ответов с различным кодом в json формате, (*6)
// 200
{
code: 200,
content: '....',
type: 'content',
method: '...'
}
// 200/Redirect
{
code: 200,
targetUrl: '....',
content: '....',
type: 'redirect',
method: '...'
}
// 110
{
code: 110,
type: 'error',
failed_rules: {...}, // поля, которые не прошли валидацию с текстом ошибки
message: ... // текст ошибки
...
}
// 120
{
code: 120,
type: 'error',
errors: {...}, // текст ошибок
failed_rules: {...} поля, которые не прошли валидацию с текстом ошибки
...
}
// Другие ошибки
{
type: 'error',
message: ... // текст ошибки
...
}
Полезные методы
Роутер
Для модуля API создан фассад RouteAPI который используется для добавления API роутов, который автоматически
добавляет к новому маршруту возможность выбора типа ответа json, xml, yaml., (*8)
API запрос можно выполнить следующим образом:, (*9)
-
site.com/api.refresh.key =>
json,
-
site.com/api.refresh.key.json =>
json,
-
site.com/api.refresh.key.xml =>
xml,
-
site.com/api.refresh.key.yaml =>
yaml
Пример, (*10)
RouteAPI::post('refresh.key', ['as' => 'api.refresh.key', 'uses' => 'API\KeysController@postRefresh']);
// Что равнозначно
Route::post('api.refresh.key{type?}', ['as' => 'api.refresh.key', 'uses' => 'API\KeysController@postRefresh'])->where('type', '\.[a-z]');
Пример контроллера с возвращением данных, (*11)
use KodiCMS\API\Http\Controllers\Controller;
class PageController extends Controller
{
public function getSearch()
{
$query = $this->getRequiredParameter('search');
...
$this->setContent(view('pages.children'));
}
}
// return JsonResponse
{
code: 200,
content: 'html data',
method: 'get',
type: 'content'
}
Пример контроллера с возвратом данных в произвольной форме, (*12)
use KodiCMS\API\Http\Controllers\Controller;
class MessageController extends Controller
{
public function sendMessage()
{
$message = $this->getRequiredParameter('message');
...
$this->testParam = '...';
// или
$this->jsonResponse['testParam'] = '...';
$this->setMessage($message);
}
}
// return JsonResponse
{
code: 200,
content: null,
testParam: '...'
type: 'content',
method: 'post',
message: 'message text'
}
Пример контроллера с редиректом, (*13)
use KodiCMS\API\Http\Controllers\Controller;
class MessageController extends Controller
{
public function sendMessage()
{
$message = $this->getRequiredParameter('message');
...
return redirect('...');
}
}
// return JsonResponse
{
code: 200,
targetUrl: '....',
content: '....',
method: 'post',
type: 'redirect'
}
Пример контроллера с выводом HTML, (*14)
use KodiCMS\API\Http\Controllers\Controller;
class MessageController extends Controller
{
public function sendMessage()
{
$message = $this->getRequiredParameter('message');
...
return view('.....');
}
}
// return JsonResponse
'html content'
Исключения
API модуль имеет свой класс исключений KodiCMS\API\Exceptions\Exception от которого лучше всего наследовать
исключения, которые используются в API контроллерах. Данный класс содержит метод responseArray, в котором содержится
список параметров, которые попадут в Response, (*15)
/**
* @var int
*/
protected $code = Response::ERROR_UNKNOWN;
public function responseArray()
{
return [
'code' => $this->getCode(),
'type' => Response::TYPE_ERROR,
'message' => $this->getMessage(),
];
}
Пример кастомного класса исключений:, (*16)
use KodiCMS\API\Exceptions\Exception;
use KodiCMS\API\Http\Response;
class ValidationException extends Exception
{
/**
* @var int
*/
protected $code = Response::ERROR_VALIDATION;
public function getFailedRules()
{
...
}
public function getErrorMessages()
{
...
}
/**
* @return array
*/
public function responseArray()
{
$data = parent::responseArray();
$data['failed_rules'] = $this->getFailedRules();
$data['errors'] = $this->getErrorMessages();
return $data;
}
}
Wallogit.com
