Свойство ответа API

Большая часть современной разработки на PHP требует создания API, будь то просто предоставление данных для javascript-ориентированного одностраничного приложения или как самостоятельный продукт. CodeIgniter предоставляет свойство API Response, которое можно использовать с любым контроллером для упрощения общих типов ответов без необходимости запоминать, какой HTTP-код состояния следует возвращать для каких типов ответов.

• Пример использования
• Обработка типов ответов
  • Справочная информация по классу

Пример использования

Следующий пример демонстрирует распространённый шаблон использования в ваших контроллерах.

<?php

namespace App\Controllers;

use CodeIgniter\API\ResponseTrait;

class Users extends \CodeIgniter\Controller
{
    use ResponseTrait;

    public function createUser()
    {
        $model = new UserModel();
        $user  = $model->save($this->request->getPost());

        // Respond with 201 status code
        return $this->respondCreated();
    }
}

В этом примере возвращается HTTP-код состояния 201 с общим сообщением состояния «Создано». Существуют методы для наиболее распространённых случаев использования:

// Generic response method
$this->respond($data, 200);

// Generic failure response
$this->fail($errors, 400);

// Item created response
$this->respondCreated($data);

// Item successfully deleted
$this->respondDeleted($data);

// Command executed by no response required
$this->respondNoContent($message);

// Client isn't authorized
$this->failUnauthorized($description);

// Forbidden action
$this->failForbidden($description);

// Resource Not Found
$this->failNotFound($description);

// Data did not validate
$this->failValidationError($description);

// Resource already exists
$this->failResourceExists($description);

// Resource previously deleted
$this->failResourceGone($description);

// Client made too many requests
$this->failTooManyRequests($description);

Обработка типов ответов

При передаче данных в любой из этих методов они определят тип данных для форматирования результатов на основе следующих критериев:

• Если данные — строка, она будет рассматриваться как HTML для отправки клиенту.
• Если данные — массив, они будут отформатированы в соответствии со значением контроллера $this->format. Если это значение пустое, будет предпринята попытка согласования типа контента с запросом клиента, при этом по умолчанию используется JSON, если ничего другого не указано в Config/Format.php, свойстве $supportedResponseFormats.

Для определения используемого форматировщика измените файл Config/Format.php. $supportedResponseFormats содержит список типов MIME, для которых приложение может автоматически форматировать ответ. По умолчанию система знает, как форматировать как XML, так и JSON-ответы:

public $supportedResponseFormats = [
    'application/json',
    'application/xml',
];

Это массив, используемый во время переговоров о формате контента для определения типа возвращаемого ответа. Если не удаётся найти соответствие между запрошенным клиентом и поддерживаемым вами форматом, первым форматом, который будет возвращён, будет формат в этом массиве.

Далее необходимо определить класс, используемый для форматирования массива данных. Это должно быть полное имя класса, и класс должен реализовывать CodeIgniter\Format\FormatterInterface. Готовые форматировщики поддерживают как JSON, так и XML:

public $formatters = [
    'application/json' => \CodeIgniter\Format\JSONFormatter::class,
    'application/xml'  => \CodeIgniter\Format\XMLFormatter::class,
];

Итак, если ваш запрос требует данных в формате JSON в заголовке Accept, массив данных, который вы передаёте любому из методов respond* или fail*, будет отформатирован классом CodeIgniter\API\JSONFormatter. Результирующие данные JSON будут отправлены клиенту.

Справочная информация по классу

setResponseFormat($format)

:param string $format Тип возвращаемого ответа, либо json, либо xml

Это определяет формат, который будет использоваться при форматировании массивов в ответах. Если вы предоставите значение null для $format, оно будет автоматически определено с помощью переговоров о формате контента.

return $this->setResponseFormat('json')->respond(['error' => false]);

respond($data[, $statusCode = 200[, $message = '']])

Параметры:	$data (mixed) – Данные для возврата клиенту. Строка или массив. $statusCode (int) – HTTP-код состояния для возврата. По умолчанию 200 $message (string) – Пользовательское сообщение «причины» для возврата.

Этот метод используется всеми другими методами в этом свойстве для возврата ответа клиенту.

Элемент $data может быть строкой или массивом. По умолчанию строка будет возвращена как HTML, а массив будет обработан с помощью json_encode и возвращён как JSON, если переговоры о формате контента не определят другой формат.

Если передаётся строка $message, она будет использоваться вместо стандартных кодов причины IANA для кода состояния ответа. Однако не каждый клиент будет учитывать пользовательские коды и будет использовать стандартные коды IANA, соответствующие коду состояния.

Примечание

Поскольку он устанавливает код состояния и тело на активном экземпляре Response, этот метод всегда должен быть последним в выполнении скрипта.

fail($messages[, int $status = 400[, string $code = null[, string $message = '']]])

Параметры:	$messages (mixed) – Строка или массив строк, содержащих сообщения об ошибках, возникшие. $status (int) – HTTP-код состояния для возврата. По умолчанию 400. $code (string) – Пользовательский, специфичный для API, код ошибки. $message (string) – Пользовательское сообщение «причины» для возврата.
Возвращает:	Многокомпонентный ответ в предпочтительном формате клиента.

Это универсальный метод для представления ответа об ошибке, используемый всеми остальными методами «ошибки».

Элемент $messages может быть строкой или массивом строк.

Параметр $status — HTTP-код состояния, который должен быть возвращён.

Поскольку многие API лучше обслуживаются с помощью пользовательских кодов ошибок, пользовательский код ошибки можно передать в третьем параметре. Если значение отсутствует, оно будет таким же, как $status.

Если передаётся строка $message, она будет использоваться вместо стандартных кодов причины IANA для кода состояния ответа. Однако не каждый клиент будет учитывать пользовательские коды и будет использовать стандартные коды IANA, соответствующие коду состояния.

Ответ — массив из двух элементов: error и messages. Элемент error содержит код состояния ошибки. Элемент messages содержит массив сообщений об ошибках. Пример:

$response = [
    'status'   => 400,
    'code'     => '321a',
    'messages' => [
        'Error message 1',
        'Error message 2',
    ],
];

respondCreated($data = null[, string $message = ''])

Параметры:	$data (mixed) – Данные для возврата клиенту. Строка или массив. $message (string) – Пользовательское сообщение «причины» для возврата.
Возвращает:	Значение метода send() объекта Response.

Устанавливает соответствующий код состояния для использования, когда новый ресурс был создан, обычно 201.

$user = $userModel->insert($data);
return $this->respondCreated($user);

respondDeleted($data = null[, string $message = ''])

Параметры:	$data (mixed) – Данные для возврата клиенту. Строка или массив. $message (string) – Пользовательское сообщение «причины» для возврата.
Возвращает:	Значение метода send() объекта Response.

Устанавливает соответствующий код состояния для использования, когда новый ресурс был удалён в результате вызова API, обычно 200.

$user = $userModel->delete($id);
return $this->respondDeleted(['id' => $id]);

respondNoContent(string $message = 'No Content')

Параметры:	$message (string) – Пользовательское сообщение «причины» для возврата.
Возвращает:	Значение метода send() объекта Response.

Устанавливает соответствующий код состояния для использования, когда команда была успешно выполнена сервером, но нет значимого ответа для отправки клиенту, обычно 204.

sleep(1);
return $this->respondNoContent();

failUnauthorized(string $description = 'Unauthorized'[, string $code = null[, string $message = '']])

Параметры:	$description (string) – Сообщение об ошибке для отображения пользователю. $code (string) – Пользовательский, специфичный для API, код ошибки. $message (string) – Пользовательское сообщение «причины» для возврата.
Возвращает:	Значение метода send() объекта Response.

Устанавливает соответствующий код состояния для использования, когда пользователь не авторизован или имеет неверную авторизацию. Код состояния — 401.

return $this->failUnauthorized('Invalid Auth token');

failForbidden(string $description = 'Forbidden'[, string $code=null[, string $message = '']])

Параметры:	$description (string) – Сообщение об ошибке для отображения пользователю. $code (string) – Пользовательский, специфичный для API, код ошибки. $message (string) – Пользовательское сообщение «причины» для возврата.
Возвращает:	Значение метода send() объекта Response.

В отличие от failUnauthorized, этот метод следует использовать, когда запрашиваемый конечный пункт API никогда не разрешается. Неавторизация подразумевает, что клиенту следует повторить попытку с другими учетными данными. Запрет означает, что клиенту не следует пытаться ещё раз, так как это не поможет. Код состояния — 403.

return $this->failForbidden('Invalid API endpoint.');

failNotFound(string $description = 'Not Found'[, string $code=null[, string $message = '']])

Параметры:	$description (string) – Сообщение об ошибке для пользователя. $code (string) – Специфичный для API код ошибки. $message (string) – Специфическое сообщение об ошибке.
Возвращаемое значение:	Значение метода send() объекта Response.

Устанавливает соответствующий код состояния, когда запрашиваемый ресурс не найден. Код состояния — 404.

return $this->failNotFound('User 13 cannot be found.');

failValidationErrors($errors[, string $code=null[, string $message = '']])

Параметры:	$errors (mixed) – Сообщение об ошибке или массив сообщений для пользователя. $code (string) – Специфичный для API код ошибки. $message (string) – Специфическое сообщение об ошибке.
Возвращаемое значение:	Значение метода send() объекта Response.

Устанавливает соответствующий код состояния, когда данные, отправленные клиентом, не прошли правила проверки. Код состояния обычно 400.

return $this->failValidationErrors($validation->getErrors());

failResourceExists(string $description = 'Conflict'[, string $code=null[, string $message = '']])

Параметры:	$description (string) – Сообщение об ошибке для пользователя. $code (string) – Специфичный для API код ошибки. $message (string) – Специфическое сообщение об ошибке.
Возвращаемое значение:	Значение метода send() объекта Response.

Устанавливает соответствующий код состояния, когда ресурс, который клиент пытается создать, уже существует. Код состояния обычно 409.

return $this->failResourceExists('A user already exists with that email.');

failResourceGone(string $description = 'Gone'[, string $code=null[, string $message = '']])

Параметры:	$description (string) – Сообщение об ошибке для пользователя. $code (string) – Специфичный для API код ошибки. $message (string) – Специфическое сообщение об ошибке.
Возвращаемое значение:	Значение метода send() объекта Response.

Устанавливает соответствующий код состояния, когда запрашиваемый ресурс был ранее удален и больше недоступен. Код состояния обычно 410.

return $this->failResourceGone('That user has been previously deleted.');

failTooManyRequests(string $description = 'Too Many Requests'[, string $code=null[, string $message = '']])

Параметры:	$description (string) – Сообщение об ошибке для пользователя. $code (string) – Специфичный для API код ошибки. $message (string) – Специфическое сообщение об ошибке.
Возвращаемое значение:	Значение метода send() объекта Response.

Устанавливает соответствующий код состояния, когда клиент слишком много раз вызывал конечную точку API. Это может быть из-за какой-либо формы ограничения или лимита запросов. Код состояния обычно 400.

return $this->failTooManyRequests('You must wait 15 seconds before making another request.');

failServerError(string $description = 'Internal Server Error'[, string $code = null[, string $message = '']])

Параметры:	$description (string) – Сообщение об ошибке для пользователя. $code (string) – Специфичный для API код ошибки. $message (string) – Специфическое сообщение об ошибке.
Возвращаемое значение:	Значение метода send() объекта Response.

Устанавливает соответствующий код состояния при ошибке сервера.

return $this->failServerError('Server error.');