Ответы API

Система ответов API KinopoiskDev для структурированной обработки данных

Система ответов KinopoiskDev предоставляет типизированные классы для обработки всех типов ответов от API kinopoisk.dev. Все классы ответов основаны на объектно-ориентированном подходе с полной типизацией и автоматической обработкой данных.

Обзор

Ответы API в KinopoiskDev используются для:

Типизации ответов - строгая типизация всех структур ответов API
Обработки данных - автоматическое преобразование JSON в объекты
Валидации - проверка корректности ответов от API
Обработки ошибок - специализированные классы для ошибок

Доступные классы ответов

Базовые классы

BaseResponseDto

Файл: BaseResponseDto.md

Базовый класс для всех ответов API:

class BaseResponseDto extends BaseModel {
    #[ApiField(name: 'status')]
    public int $status;

    #[ApiField(name: 'message')]
    public string $message;

    #[ApiField(name: 'timestamp')]
    public string $timestamp;
}

Возможности:

Базовые поля всех ответов
Статус и сообщения
Временные метки
Общая структура

BaseDocsResponseDto

Файл: BaseDocsResponseDto.md

Базовый класс для ответов с документами:

class BaseDocsResponseDto extends BaseResponseDto {
    #[ApiField(name: 'docs')]
    public array $docs;

    #[ApiField(name: 'total')]
    public int $total;

    #[ApiField(name: 'limit')]
    public int $limit;

    #[ApiField(name: 'page')]
    public int $page;

    #[ApiField(name: 'pages')]
    public int $pages;
}

Возможности:

Пагинация результатов
Общее количество документов
Лимиты и страницы
Массивы документов

ErrorResponseDto

Файл: ErrorResponseDto.md

Базовый класс для ответов с ошибками:

class ErrorResponseDto extends BaseResponseDto {
    #[ApiField(name: 'error')]
    public string $error;

    #[ApiField(name: 'errorCode')]
    public int $errorCode;

    #[ApiField(name: 'details')]
    public array $details;
}

Возможности:

Информация об ошибках
Коды ошибок
Детали ошибок
Обработка исключений

API ответы

MovieDocsResponseDto

Файл: Api/MovieDocsResponseDto.md

Ответ для поиска фильмов:

class MovieDocsResponseDto extends BaseDocsResponseDto {
    #[ApiField(name: 'docs')]
    public array $docs; // array<Movie>
}

Возможности:

Массив фильмов
Пагинация
Метаданные поиска

PersonDocsResponseDto

Файл: Api/PersonDocsResponseDto.md

Ответ для поиска персон:

class PersonDocsResponseDto extends BaseDocsResponseDto {
    #[ApiField(name: 'docs')]
    public array $docs; // array<Person>
}

Возможности:

Массив персон
Пагинация
Метаданные поиска

SearchMovieResponseDto

Файл: Api/SearchMovieResponseDto.md

Ответ для поиска фильмов с краткой информацией:

class SearchMovieResponseDto extends BaseDocsResponseDto {
    #[ApiField(name: 'docs')]
    public array $docs; // array<SearchMovie>
}

Возможности:

Краткая информация о фильмах
Оптимизированная структура
Быстрая загрузка

SearchPersonResponseDto

Файл: Api/SearchPersonResponseDto.md

Ответ для поиска персон с краткой информацией:

class SearchPersonResponseDto extends BaseDocsResponseDto {
    #[ApiField(name: 'docs')]
    public array $docs; // array<Person>
}

Возможности:

Краткая информация о персонах
Оптимизированная структура
Быстрая загрузка

ImageDocsResponseDto

Файл: Api/ImageDocsResponseDto.md

Ответ для получения изображений:

class ImageDocsResponseDto extends BaseDocsResponseDto {
    #[ApiField(name: 'docs')]
    public array $docs; // array<Image>
}

Возможности:

Массив изображений
Метаданные изображений
Фильтрация по типам

KeywordDocsResponseDto

Файл: Api/KeywordDocsResponseDto.md

Ответ для поиска ключевых слов:

class KeywordDocsResponseDto extends BaseDocsResponseDto {
    #[ApiField(name: 'docs')]
    public array $docs; // array<Keyword>
}

Возможности:

Массив ключевых слов
Метаданные поиска
Фильтрация по популярности

ReviewDocsResponseDto

Файл: Api/ReviewDocsResponseDto.md

Ответ для поиска отзывов:

class ReviewDocsResponseDto extends BaseDocsResponseDto {
    #[ApiField(name: 'docs')]
    public array $docs; // array<Review>
}

Возможности:

Массив отзывов
Типизация отзывов
Метаданные поиска

SeasonDocsResponseDto

Файл: Api/SeasonDocsResponseDto.md

Ответ для получения сезонов:

class SeasonDocsResponseDto extends BaseDocsResponseDto {
    #[ApiField(name: 'docs')]
    public array $docs; // array<Season>
}

Возможности:

Массив сезонов
Информация об эпизодах
Метаданные сериала

StudioDocsResponseDto

Файл: Api/StudioDocsResponseDto.md

Ответ для поиска студий:

class StudioDocsResponseDto extends BaseDocsResponseDto {
    #[ApiField(name: 'docs')]
    public array $docs; // array<Studio>
}

Возможности:

Массив студий
Типы студий
Метаданные поиска

ListDocsResponseDto

Файл: Api/ListDocsResponseDto.md

Ответ для получения списков:

class ListDocsResponseDto extends BaseDocsResponseDto {
    #[ApiField(name: 'docs')]
    public array $docs; // array<Lists>
}

Возможности:

Массив списков
Категории списков
Метаданные

MovieAwardDocsResponseDto

Файл: Api/MovieAwardDocsResponseDto.md

Ответ для получения наград фильмов:

class MovieAwardDocsResponseDto extends BaseDocsResponseDto {
    #[ApiField(name: 'docs')]
    public array $docs; // array<MovieAward>
}

Возможности:

Массив наград
Номинации и победы
Метаданные наград

PersonAwardDocsResponseDto

Файл: Api/PersonAwardDocsResponseDto.md

Ответ для получения наград персон:

class PersonAwardDocsResponseDto extends BaseDocsResponseDto {
    #[ApiField(name: 'docs')]
    public array $docs; // array<PersonAward>
}

Возможности:

Массив наград персон
Номинации и победы
Метаданные наград

SearchStudioResponseDto

Файл: Api/SearchStudioResponseDto.md

Ответ для поиска студий:

class SearchStudioResponseDto extends BaseDocsResponseDto {
    #[ApiField(name: 'docs')]
    public array $docs; // array<Studio>
}

Возможности:

Массив студий
Типы студий
Метаданные поиска

PossibleValueDto

Файл: Api/PossibleValueDto.md

Ответ для получения возможных значений:

class PossibleValueDto extends BaseResponseDto {
    #[ApiField(name: 'values')]
    public array $values;
}

Возможности:

Возможные значения полей
Справочная информация
Валидация параметров

Классы ошибок

UnauthorizedErrorResponseDto

Файл: Errors/UnauthorizedErrorResponseDto.md

Ответ для ошибки 401 (Неавторизован):

class UnauthorizedErrorResponseDto extends ErrorResponseDto {
    #[ApiField(name: 'error')]
    public string $error = 'Unauthorized';

    #[ApiField(name: 'errorCode')]
    public int $errorCode = 401;
}

Возможности:

Обработка ошибок авторизации
Неверные API ключи
Истекшие токены

ForbiddenErrorResponseDto

Файл: Errors/ForbiddenErrorResponseDto.md

Ответ для ошибки 403 (Запрещено):

class ForbiddenErrorResponseDto extends ErrorResponseDto {
    #[ApiField(name: 'error')]
    public string $error = 'Forbidden';

    #[ApiField(name: 'errorCode')]
    public int $errorCode = 403;
}

Возможности:

Обработка ошибок доступа
Недостаточные права
Блокировка запросов

NotFoundErrorResponseDto

Файл: Errors/NotFoundErrorResponseDto.md

Ответ для ошибки 404 (Не найдено):

class NotFoundErrorResponseDto extends ErrorResponseDto {
    #[ApiField(name: 'error')]
    public string $error = 'Not Found';

    #[ApiField(name: 'errorCode')]
    public int $errorCode = 404;
}

Возможности:

Обработка ошибок поиска
Несуществующие ресурсы
Неверные ID

Использование

Обработка успешных ответов

<?php

use KinopoiskDev\Responses\Api\MovieDocsResponseDto;
use KinopoiskDev\Responses\Api\PersonDocsResponseDto;

// Автоматическое создание из JSON ответа
$jsonResponse = '{"status":200,"docs":[...],"total":100,"limit":20}';
$response = MovieDocsResponseDto::fromArray(json_decode($jsonResponse, true));

// Доступ к данным
echo $response->status; // 200
echo $response->total; // 100
echo count($response->docs); // количество фильмов

// Работа с документами
foreach ($response->docs as $movie) {
    echo $movie->name . " (" . $movie->year . ")\n";
}

Обработка ошибок

<?php

use KinopoiskDev\Responses\Errors\UnauthorizedErrorResponseDto;
use KinopoiskDev\Responses\Errors\NotFoundErrorResponseDto;

// Обработка ошибки авторизации
$errorJson = '{"status":401,"error":"Unauthorized","errorCode":401}';
$error = UnauthorizedErrorResponseDto::fromArray(json_decode($errorJson, true));

echo $error->error; // "Unauthorized"
echo $error->errorCode; // 401

// Обработка ошибки поиска
$notFoundJson = '{"status":404,"error":"Not Found","errorCode":404}';
$notFound = NotFoundErrorResponseDto::fromArray(json_decode($notFoundJson, true));

echo $notFound->error; // "Not Found"

Работа с пагинацией

<?php

use KinopoiskDev\Responses\Api\MovieDocsResponseDto;

$response = MovieDocsResponseDto::fromArray($data);

// Информация о пагинации
echo "Всего фильмов: " . $response->total . "\n";
echo "На странице: " . $response->limit . "\n";
echo "Текущая страница: " . $response->page . "\n";
echo "Всего страниц: " . $response->pages . "\n";

// Проверка наличия следующей страницы
if ($response->page < $response->pages) {
    echo "Есть следующая страница\n";
}

// Получение документов
$movies = $response->docs;
foreach ($movies as $movie) {
    echo $movie->name . "\n";
}

Автоматическая обработка в HTTP запросах

<?php

use KinopoiskDev\Http\MovieRequests;
use KinopoiskDev\Responses\Api\MovieDocsResponseDto;
use KinopoiskDev\Responses\Errors\UnauthorizedErrorResponseDto;

$requests = new MovieRequests(apiToken: 'your-token');

try {
    $response = $requests->searchMovies($filter);
    // Автоматически создается MovieDocsResponseDto

    foreach ($response->docs as $movie) {
        echo $movie->name . "\n";
    }

} catch (KinopoiskResponseException $e) {
    if ($e->getCode() === 401) {
        // Автоматически создается UnauthorizedErrorResponseDto
        echo "Ошибка авторизации: " . $e->getMessage();
    }
}

Интеграция с исключениями

Автоматическое создание исключений

<?php

use KinopoiskDev\Responses\Errors\UnauthorizedErrorResponseDto;
use KinopoiskDev\Exceptions\KinopoiskResponseException;

// Автоматическое создание исключения из ответа ошибки
$errorResponse = UnauthorizedErrorResponseDto::fromArray($errorData);
$exception = new KinopoiskResponseException(
    UnauthorizedErrorResponseDto::class,
    $previousException
);

// Информация из ответа автоматически извлекается
echo $exception->getMessage(); // "Unauthorized"
echo $exception->getCode(); // 401

Обработка различных типов ошибок

try {
    $response = $requests->getMovieById(999999);
} catch (KinopoiskResponseException $e) {
    switch ($e->getCode()) {
        case 401:
            // UnauthorizedErrorResponseDto
            echo "Неверный API ключ";
            break;
        case 403:
            // ForbiddenErrorResponseDto
            echo "Доступ запрещен";
            break;
        case 404:
            // NotFoundErrorResponseDto
            echo "Фильм не найден";
            break;
        default:
            echo "Ошибка API: " . $e->getMessage();
    }
}

Связанные разделы

Models - модели данных в ответах
Exceptions - исключения для обработки ошибок
Http - HTTP запросы, возвращающие ответы
Attributes - атрибуты для валидации ответов

Преимущества

Типобезопасность

// Строгая типизация всех ответов
$response = MovieDocsResponseDto::fromArray($data);
$response->docs;        // array<Movie>
$response->total;       // int
$response->limit;       // int
$response->page;        // int

Автоматическая обработка

// Автоматическое создание из JSON
$response = MovieDocsResponseDto::fromArray(json_decode($json, true));

// Автоматическая валидация
$response->validate();

// Автоматическое создание исключений
throw new KinopoiskResponseException(UnauthorizedErrorResponseDto::class);

Единообразный интерфейс

// Все ответы имеют одинаковую структуру
$response->status;    // Статус ответа
$response->message;   // Сообщение
$response->timestamp; // Временная метка

// Все ответы с документами поддерживают пагинацию
$response->docs;      // Массив документов
$response->total;     // Общее количество
$response->limit;     // Лимит на страницу
$response->page;      // Текущая страница
$response->pages;     // Общее количество страниц

Полезные ссылки

Models - модели данных
Exceptions - исключения
Http - HTTP запросы
Attributes - атрибуты валидации

Ответы API KinopoiskDev - обеспечивают типобезопасность и автоматическую обработку всех ответов от API kinopoisk.dev.

Ответы API

On this page