Документация API
Документация API
JSON-API каталога оцифрованных материалов мультфильма «Незнайка на Луне»: записи, персонажи, справочники и файлы. Доступ выдаётся по API-ключу, ключи создаёт администратор проекта в панели.
Базовый адрес
https://insidethemoon.ru/api/v2
Аутентификация
Ключ передаётся в заголовке запроса. Поддерживаются два варианта:
Authorization: Bearer itm_<prefix>_<secret>
X-API-Key: itm_<prefix>_<secret>
Ключ в query-параметрах не принимается. При отсутствии, неверном или отозванном ключе возвращается 401.
Формат ответа
Успешный ответ — JSON-объект. Поля верхнего уровня:
| Поле | Тип | Описание |
|---|---|---|
message | string | При успехе — пустая строка; при ошибке — текст на английском. |
data | object, array или null | Данные ответа; при ошибке — null. |
meta | object | Только у списков: page, per_page, total, pages, sort. |
200— успех;400— неверные параметры;401— нет, неверный или отозванный ключ;403— неверная или просроченная подпись ссылки на файл;404— объект с таким id не найден;500— внутренняя ошибка.
Тексты message — на английском. Кодировка ответа — UTF-8, кеширование запрещено (Cache-Control: no-store).
Пагинация и сортировка
page— номер страницы, с 1;per_page— записей на странице, 1..100, по умолчанию 50;sort— для записей:new(по умолчанию),old,title; для персонажей:name(по умолчанию),id,-id.
Фильтры списка записей: product, content_type, condition, file_type, character, featured (0/1), date (ГГГГ-ММ-ДД), month (ГГГГ-ММ). Список персонажей фильтруется по product.
Состав данных
Даты — в формате ГГГГ-ММ-ДД; флаги — булевы.
Эндпоинты
| Метод | Путь | Назначение |
|---|---|---|
| GET | /items | Список записей каталога |
| GET | /items/{ID} | Запись с описанием и техническими характеристиками |
| GET | /characters | Список персонажей |
| GET | /characters/{ID} | Персонаж с числом записей |
| GET | /datasets | Все справочники |
| GET | /datasets/{name} | Записи справочника |
Возвращаемые структуры
Запись каталога
Сведения о записи в /items и /items/{ID}:
| Поле | Тип | Описание |
|---|---|---|
id | int | Идентификатор записи. |
title | string | Название записи. |
title_counter | int | Порядковый номер в серии одноимённых названий. |
display_title | string | Отображаемое название с номером. |
date_add | string | Дата добавления, ГГГГ-ММ-ДД. |
featured | bool | Признак избранной записи. |
product | object | Произведение: id (int) и name (string). |
content_type | object | Тип носителя: id (int), name и description (string). |
condition | object | Состояние оригинала: id (int), name и description (string). |
file_type | object | Тип файла: id (int), type и mime (string), auto_preview (bool). |
characters | array | Имена персонажей. |
files | object | Подписанные ссылки и метаданные файлов (см. «Файлы»). |
description | string | Только в /items/{ID}: описание записи. |
tech | object | Только в /items/{ID}: pages (int или null), ocr (bool или null), dpi (int или null), color_model (string или null), color_depth (int или null), compression (string или null). |
Персонаж
Сведения о персонаже в /characters и /characters/{ID}:
| Поле | Тип | Описание |
|---|---|---|
id | int | Идентификатор персонажа. |
name | string | Имя персонажа. |
product | object | Произведение: id (int) и name (string). |
item_count | int | Число опубликованных неудалённых записей с персонажем. |
Справочники
/datasets возвращает объект с массивами products, content_types, conditions, file_types, file_titles. Запись /datasets/{name} возвращает массив записей одного справочника.
Имена справочников: products, content-types, conditions, file-types, file-titles. Поля записей:
Произведения (products)
| Поле | Тип | Описание |
|---|---|---|
id | int | Идентификатор произведения. |
name | string | Название произведения. |
Типы носителей (content_types)
| Поле | Тип | Описание |
|---|---|---|
id | int | Идентификатор типа носителя. |
name | string | Название типа носителя. |
description | string | Пояснение. |
Состояния (conditions)
| Поле | Тип | Описание |
|---|---|---|
id | int | Идентификатор состояния. |
name | string | Название состояния. |
description | string | Пояснение. |
Типы файлов (file_types)
| Поле | Тип | Описание |
|---|---|---|
id | int | Идентификатор типа файла. |
type | string | Расширение файла. |
auto_preview | bool | true — превью из оригинала; false — нужно JPEG-превью. |
mime | string | Ожидаемый MIME-тип загрузки. |
Универсальные названия (file_titles)
| Поле | Тип | Описание |
|---|---|---|
id | int | Идентификатор названия. |
title | string | Универсальное название. |
Неверное имя справочника даёт 404.
Файлы
Объект files в записи каталога содержит подписанные ссылки и метаданные файлов:
| Поле | Тип | Описание |
|---|---|---|
hash | string | Публичный идентификатор медиа. |
preview_small | object | Малое превью: url, mime, size_bytes, checksum_sha256. |
preview_big | object | Большое превью: те же поля. |
preview_xlarge | object | Увеличенное превью: те же поля. |
original | object | Оригинал: download_url, mime, size_bytes, checksum_sha256. |
compressed | object | Сжатая JPEG-копия: download_url, mime, size_bytes, checksum_sha256. |
checksum_sha256— SHA-256 файла;null, пока метаданные не рассчитаны.- Ссылки подписаны и действуют 1 час; их можно использовать многократно до истечения срока.
- Неверная подпись или истёкший срок дают
403.

