API

Оглавление

API предоставляет возможности для программного взаимодействия с системой из разных мест, например, из своих собственных сущностей (модули, темы и т.д), а также доступ из внешних ресурсов. Весь функционал распределен по определенным секциям системы и делится на API двух видов:

• Внутреннее (internal) - доступно только внутри системы, включая доступ из пользовательских сущностей (модулей, тем и т.д.);
• Внешнее (external) - доступно из любого места, включая доступ со сторонних ресурсов.

Все предоставляемые методы API рекомендуется задавать явным способом, для чего в сервисных файлах требуется их описание в виде:

class Service {
	// ...
	
	public $api = [
		'get_user_id' => [
			'type' => 'internal', // external или internal, если не указано - internal
			'access' => ['administrator',], // доступ только для указанных ролей пользователей, если не указано - доступ для всех
			'format' => 'json_object', // json или json_object, если не указано - данные будут возвращены в обычном виде
			'method' => 'get_user_id_plus', // метод для переопределения, если не указано - будет вызван первоначальный
		],
	];

	function get_api() {
		return $this->api;
	}
	
	// ...
}

Внешние методы API необходимо вызывать по адресу вида https://example.com/api, на который необходимо отправить данные методом POST или GET:

• key - ключ для API, обычно 12345. Ключ для сравнения задается в настройках (файл settings.php - api_key);
• module - вызываемый модуль;
• method - вызываемый метод в указанном модуле;
• data - прочие различные данные (необязательно).

Авторизация для доступа к API может понадобиться в некоторых сценариях - например, если у API-метода задан массив ролей с доступом. Для этого могут быть использованы следующие механизмы авторизации (данные для авторизации отправляются вместе с остальными данными методом POST или GET):

• может быть отправлен авторизационный токен - параметр token, система автоматически авторизует пользователя. Такой токен может быть получен при авторизации с помощью различных приложений или интерфейсов, которые запрашивают логин и пароль пользователя;
• возможно восстановление авторизованной сессии посредством отправки идентификатора сессии - имя сессии задается в настройках системы (файл settings.php - session_name), например, EQSASH_SESSION.