API

Модуль API

Модуль API используется для удобства работы с API запросами. На данный момент этот модуль предоставляет всего лишь контроллер, с набором методов, которые помогут организовать работу с AJAX запросами.

Контроллер

Контроллер необходимо наследовать от KodiCMS\API\Http\Controllers\System\Controller, после чего он начнет возвращать все ответы (ошибки и т.д.) в определенном формате с возможностью выбора типа ответа (json, xml, yaml):

Пример ответа:

{
	code: 200,
	content: '....',
	type: 'content',
	method: '...'
}

Коды ответов:

• 200 - ok
• 110 - не передан обязательный параметр в запросе
• 120 - ошибка валидации
• 130 - неизвестная ошибка
• 140 - ошибка токена
• 150 - Попытка в модели установить значение защищенного поля
• 220 - ошибка прав доступа
• 403 - Неавторизован
• 404 - страница не найдена

Тип ответа

• error - ошибка
• content - ответ
• redirect - редирект

Пример ответов с различным кодом в json формате

// 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 необходима авторизация пользователя. Существует два варианта предоставления доступа не авторизованным пользователям к контроллеру:

-  Отключить проверку авторизации, установив `protected $authRequired = false;`
-  Добавить название экшена в массив `protected $allowedActions = [];`, тогда будет предоставлен доступ к определенному экшену

Полезные методы

• getParameter($key, $default = NULL, $isRequired = false) - получение параметра переданного в запросе
• getRequiredParameter($key, $rules = true) - получение обязательного параметра, Вторым параметром можно указать правила валидации (true == 'required'), выбрасывает ошибку 110
• setMessage($message) - передача сообщения в ответ
• setErrors(array $errors) - передача ошибок в ответ
• setContent($data) - передача данных в ответ. Если передается view, то он будет преобразован в HTML

Полезные параметры

• jsonResponse - данные, которые будут переданы в ответ и преобразованы в JSON
• requiredFields - ожидаемые поля в виде ['action' => ['param1, 'param2']]
• authRequired - только авторизованные пользователи

Роутер

Для модуля API создан фассад RouteAPI который используется для добавления API роутов, который автоматически добавляет к новому маршруту возможность указания типа ответа json, xml, yaml.

API запрос можно выполнить следующим образом:

• 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

Пример

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]');

---

Пример контроллера с возвращением данных

use KodiCMS\API\Http\Controllers\System\Controller;
class PageController extends Controller
{
	public function getSearch()
	{
		$query = $this->getRequiredParameter('search');
		
		...

		$this->setContent(view('pages::pages.children'));
	}
}

Пример контроллера с возвратом данных в произвольной форме

use KodiCMS\API\Http\Controllers\System\Controller;
class MessageController extends Controller
{
	public function sendMessage()
	{
		$message = $this->getRequiredParameter('message');
		
		...

		$this->testParam = '...';
		// или
		$this->jsonResponse['testParam'] = '...';
	}
}

Пример контроллера с редиректом

use KodiCMS\API\Http\Controllers\System\Controller;
class MessageController extends Controller
{
	public function sendMessage()
	{
		$message = $this->getRequiredParameter('message');
		
		...

		return redirect('...');
	}
}

---

Исключения

API модуль имеет свой класс исключений KodiCMS\API\Exceptions\Exception от которого лучше всего наследовать исключения, которые используются в API контроллерах. Данный класс содержит метод responseArray, в котором содержится список параметров, которые попадут в Response

/**
 * @var int
 */
protected $code = Response::ERROR_UNKNOWN;

public function responseArray()
{
	return [
		'code' => $this->getCode(),
		'type' => Response::TYPE_ERROR,
		'message' => $this->getMessage(),
	];
}

Пример кастомного класса исключений:

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;
	}
}