Да это очень хорошо, что я неисправим!
Если я буду исправим, вся наша интересная
жизнь сразу станет неинтересной!

Inside the MoonInside the Moon

Документация API

Документация API

JSON-API каталога оцифрованных материалов мультфильма «Незнайка на Луне»: записи, персонажи, справочники и файлы. Доступ выдаётся по API-ключу, ключи создаёт администратор проекта в панели.

Никому не передавайте ключ и не публикуйте его. В противном случае ключ может быть отозван администрацией.

Связаться с нами

Базовый адрес

https://insidethemoon.ru/api/v2

Аутентификация

Ключ передаётся в заголовке запроса. Поддерживаются два варианта:

Authorization: Bearer itm_<prefix>_<secret>
X-API-Key: itm_<prefix>_<secret>

Ключ в query-параметрах не принимается. При отсутствии, неверном или отозванном ключе возвращается 401.

Формат ответа

Успешный ответ — JSON-объект. Поля верхнего уровня:

ПолеТипОписание
messagestringПри успехе — пустая строка; при ошибке — текст на английском.
dataobject, array или nullДанные ответа; при ошибке — null.
metaobjectТолько у списков: 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}:

ПолеТипОписание
idintИдентификатор записи.
titlestringНазвание записи.
title_counterintПорядковый номер в серии одноимённых названий.
display_titlestringОтображаемое название с номером.
date_addstringДата добавления, ГГГГ-ММ-ДД.
featuredboolПризнак избранной записи.
productobjectПроизведение: id (int) и name (string).
content_typeobjectТип носителя: id (int), name и description (string).
conditionobjectСостояние оригинала: id (int), name и description (string).
file_typeobjectТип файла: id (int), type и mime (string), auto_preview (bool).
charactersarrayИмена персонажей.
filesobjectПодписанные ссылки и метаданные файлов (см. «Файлы»).
descriptionstringТолько в /items/{ID}: описание записи.
techobjectТолько в /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}:

ПолеТипОписание
idintИдентификатор персонажа.
namestringИмя персонажа.
productobjectПроизведение: id (int) и name (string).
item_countintЧисло опубликованных неудалённых записей с персонажем.

Справочники

/datasets возвращает объект с массивами products, content_types, conditions, file_types, file_titles. Запись /datasets/{name} возвращает массив записей одного справочника.

Имена справочников: products, content-types, conditions, file-types, file-titles. Поля записей:

Произведения (products)
ПолеТипОписание
idintИдентификатор произведения.
namestringНазвание произведения.
Типы носителей (content_types)
ПолеТипОписание
idintИдентификатор типа носителя.
namestringНазвание типа носителя.
descriptionstringПояснение.
Состояния (conditions)
ПолеТипОписание
idintИдентификатор состояния.
namestringНазвание состояния.
descriptionstringПояснение.
Типы файлов (file_types)
ПолеТипОписание
idintИдентификатор типа файла.
typestringРасширение файла.
auto_previewbooltrue — превью из оригинала; false — нужно JPEG-превью.
mimestringОжидаемый MIME-тип загрузки.
Универсальные названия (file_titles)
ПолеТипОписание
idintИдентификатор названия.
titlestringУниверсальное название.

Неверное имя справочника даёт 404.

Файлы

Объект files в записи каталога содержит подписанные ссылки и метаданные файлов:

ПолеТипОписание
hashstringПубличный идентификатор медиа.
preview_smallobjectМалое превью: url, mime, size_bytes, checksum_sha256.
preview_bigobjectБольшое превью: те же поля.
preview_xlargeobjectУвеличенное превью: те же поля.
originalobjectОригинал: download_url, mime, size_bytes, checksum_sha256.
compressedobjectСжатая JPEG-копия: download_url, mime, size_bytes, checksum_sha256.
  • checksum_sha256 — SHA-256 файла; null, пока метаданные не рассчитаны.
  • Ссылки подписаны и действуют 1 час; их можно использовать многократно до истечения срока.
  • Неверная подпись или истёкший срок дают 403.