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

JSON API для доступа к данным архива: фонограммам, рулонам, справочникам, атрибутам и файлам. Доступ предоставляется по API-ключу, выданному администрацией архива.

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

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

t.me/vidachestvo

audio@retro-archive.ru

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

https://retro-archive.ru/api/v2

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

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

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

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

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

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

Поле	Тип	Описание
`message`	string	При успехе — пустая строка; при ошибке — текст на английском.
`data`	object, array или null	Данные ответа; при ошибке — `null`.
`meta`	object	Только у списков: `page`, `per_page`, `total`, `pages` — целые числа.

200 — успех;
400 — неверные параметры;
401 — нет, неверный или отозванный ключ;
404 — объект с таким id не найден;
500 — внутренняя ошибка.

Тексты message — на английском. Кодировка ответа — UTF-8, кеширование запрещено (Cache-Control: no-store).

Пагинация и фильтры

page — номер страницы, с 1;
per_page — записей на странице, 1..100, по умолчанию 50;
sort — id (по возрастанию, по умолчанию) или -id;
updated_since=ГГГГ-ММ-ДД — только записи, изменённые с указанной даты (для инкрементальной синхронизации).

Дополнительные фильтры: q (поиск по коду/заголовку), record, year, fund, content_type, redaction, attribute (для значений и свойств атрибутов).

Состав данных

Даты — в формате MySQL (ГГГГ-ММ-ДД ЧЧ:ММ:СС, серверное время), флаги — булевы.

Эндпоинты

Метод	Путь	Назначение
GET	`/records`	Список фонограмм
GET	`/records/{id}`	Фонограмма с краткими сведениями о рулонах
GET	`/reels`	Список рулонов
GET	`/reels/{id}`	Полные сведения о рулоне
GET	`/datasets`	Список справочников
GET	`/datasets/{name}`	Записи справочника
GET	`/datasets/{name}/{id}`	Одна запись справочника
GET	`/attribute-values`	Значения атрибутов
GET	`/attribute-properties`	Свойства атрибутов

Возвращаемые структуры

Фонограмма

Сведения о фонограмме в /records и /records/{id}:

Поле	Тип	Описание
`id`	int	Идентификатор фонограммы.
`code`	string	Код фонограммы.
`gdrz`	bool	Принадлежность фонду ГДРЗ.
`total_reels`	int	Количество рулонов согласно формуляру фонограммы.
`total_duration`	int	Длительность согласно формуляру фонограммы, секунды.
`total_duration_hms`	string	Та же длительность в формате `ЧЧ:ММ:СС`.
`reel_count`	int	Число доступных рулонов.
`reel_duration`	int	Суммарная длительность доступных рулонов, секунды.
`reel_duration_hms`	string	Та же длительность в формате `ЧЧ:ММ:СС`.
`created_at`, `updated_at`	string или null	Даты создания и изменения.
`reels`	array	Только в `/records/{id}`: массив кратких сведений о рулонах (см. ниже).

Краткие сведения о рулоне

Элемент списка /reels и вложенный reels в ответе фонограммы:

Поле	Тип	Описание
`id`	int	Идентификатор рулона.
`record`	int	Идентификатор фонограммы.
`reel_number`	int	Номер рулона в фонограмме.
`code`	string	Код рулона; для фонограмм с несколькими рулонами содержит номер.
`title`, `subtitle`	string	Название и подзаголовок.
`duration`	int	Длительность, секунды.
`duration_hms`	string	Длительность в формате `ЧЧ:ММ:СС`.
`date_recording`, `date_copy`	string или null	Даты записи и переписи.
`fund`	object или null	Фонд — запись справочника «Фонды» с полями `id` (int) и `name` (string).
`media_type`	object или null	Тип носителя — запись справочника «Типы носителей» с полями `id` (int) и `name` (string).
`files`	object	Наличие файлов: `audio`, `image`, `zip` (bool), `channels` (int или null).
`created_at`, `updated_at`	string или null	Даты создания и изменения.

Полные сведения о рулоне

Полная структура ответа /reels/{id}:

Поле	Тип	Описание
`id`	int	Идентификатор рулона.
`record`	int	Идентификатор фонограммы.
`reel_number`	int	Номер рулона в фонограмме.
`code`	string	Код рулона; для фонограмм с несколькими рулонами содержит номер.
`title`, `subtitle`	string	Название и подзаголовок.
`duration`	int	Длительность, секунды.
`duration_hms`	string	Длительность в формате `ЧЧ:ММ:СС`.
`date_recording`, `date_copy`	string или null	Даты записи и переписи.
`fund`	object или null	Фонд — полная запись справочника «Фонды» (см. «Справочник»).
`media_type`	object или null	Тип носителя — полная запись справочника «Типы носителей» (см. «Справочник»).
`comment`	string	Комментарий к рулону.
`variant`	object или null	Вариант записи — запись справочника «Варианты записи» (см. «Справочник»).
`media`	object или null	Вид носителя — запись справочника «Виды носителей» (см. «Справочник»).
`hardware_type`	object или null	Тип оборудования оцифровки — запись справочника (см. «Справочник»).
`hardware`	object или null	Оборудование оцифровки — запись справочника (см. «Справочник»).
`audio_interface`	object или null	Аудиоинтерфейс — запись справочника (см. «Справочник»).
`tape_speed`	object или null	Скорость ленты — запись справочника (см. «Справочник»).
`content_types`	array	Типы содержания: объекты `id` (int) и `name` (string).
`redactions`	array	Редакции: объекты `id` (int) и `name` (string).
`tracks`	array	Объекты `number` (int) и `name` (string).
`attributes`	array	Плоский список атрибутов рулона (см. ниже).
`files`	object	Полный объект файлов (см. «Файлы»).
`created_at`, `updated_at`	string или null	Даты создания и изменения.

Атрибут рулона

Поле	Тип	Описание
`track`	int или null	Номер дорожки.
`attribute`	object	`id`, `name`; `type` — объект `id` и `name`.
`value`	object	Значение: `id` (int) и `name` (string).
`property`	object или null	Свойство: `id` (int) и `name` (string).
`parent_value_id`, `parent_property_id`	int или null	Родительские значение и свойство для вложенных атрибутов.

Справочник

/datasets возвращает краткий список справочников; элемент списка:

Поле	Тип	Описание
`name`	string	Имя справочника.
`title`	string	Название справочника для интерфейса.

Запись /datasets/{name} и /datasets/{name}/{id}. Поля по справочникам:

Атрибуты (`attribute`)

Поле	Тип	Описание
`id`	int	Идентификатор записи.
`name`	string	Название.
`type`	int	Идентификатор типа атрибута.
`created_at`, `updated_at`	string или null	Даты создания и изменения.

Типы атрибутов (`attribute_type`)

Поле	Тип	Описание
`id`	int	Идентификатор записи.
`name`	string	Название.
`nested`	0/1	Признак вложенности.
`created_at`, `updated_at`	string или null	Даты создания и изменения.

Аудиоинтерфейсы (`audio_interface`)

Поле	Тип	Описание
`id`	int	Идентификатор записи.
`name`	string	Название.
`created_at`, `updated_at`	string или null	Даты создания и изменения.

Типы содержания (`content_type`)

Поле	Тип	Описание
`id`	int	Идентификатор записи.
`name`	string	Название.
`created_at`, `updated_at`	string или null	Даты создания и изменения.

Фонды (`fund`)

Поле	Тип	Описание
`id`	int	Идентификатор записи.
`name`	string	Название.
`created_at`, `updated_at`	string или null	Даты создания и изменения.

Оборудование (`hardware`)

Поле	Тип	Описание
`id`	int	Идентификатор записи.
`name`	string	Название.
`type`	int или null	Идентификатор типа оборудования.
`created_at`, `updated_at`	string или null	Даты создания и изменения.

Типы магнитофонов (`hardware_type`)

Справочник hardware_type не входит в /datasets; его запись возвращается как поле hardware_type в полных сведениях о рулоне.

Поле	Тип	Описание
`id`	int	Идентификатор записи.
`name`	string	Название.
`created_at`, `updated_at`	string или null	Даты создания и изменения.

Виды носителей (`media`)

Поле	Тип	Описание
`id`	int	Идентификатор записи.
`name`	string	Название.
`type`	int или null	Идентификатор типа носителя.
`created_at`, `updated_at`	string или null	Даты создания и изменения.

Типы носителей (`media_type`)

Поле	Тип	Описание
`id`	int	Идентификатор записи.
`name`	string	Название.
`tape_speed`	int	Скорость ленты.
`created_at`, `updated_at`	string или null	Даты создания и изменения.

Редакции (`redaction`)

Поле	Тип	Описание
`id`	int	Идентификатор записи.
`name`	string	Название.
`full_name`	string	Полное название.
`content_types`	array int	Идентификаторы типов содержания.
`created_at`, `updated_at`	string или null	Даты создания и изменения.

Скорости ленты (`tape_speed`)

Поле	Тип	Описание
`id`	int	Идентификатор записи.
`name`	string	Название.
`created_at`, `updated_at`	string или null	Даты создания и изменения.

Варианты записи (`variant`)

Поле	Тип	Описание
`id`	int	Идентификатор записи.
`name`	string	Название.
`stereo`	bool	Стерео.
`created_at`, `updated_at`	string или null	Даты создания и изменения.

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

Значение и свойство атрибута

Элементы /attribute-values и /attribute-properties:

Поле	Тип	Описание
`id`	int	Идентификатор значения или свойства.
`name`	string	Название.
`attribute`	object	`id`, `name`; `type` — объект `id` и `name`.

Файлы

Полный объект files в ответе /reels/{id}; если у рулона нет медиа — пустой объект:

Поле	Тип	Описание
`hash`	string	Публичный идентификатор медиа.
`audio`	object	При наличии аудио: ссылки, параметры и метаданные.
`audio.stream_url`	string	Ссылка на mp3 для прослушивания.
`audio.mp3_url`	string	Ссылка на mp3 для скачивания.
`audio.flac_url`	string	Ссылка на flac для скачивания.
`audio.channels`, `audio.bit_depth`, `audio.sampling_rate`	int или null	Технические параметры аудио.
`audio.mp3`, `audio.flac`	object	Метаданные: `size_bytes` (int или null), `checksum_sha256` (string или null).
`image`	object	При наличии изображения: `preview_url`, `full_url`, `download_url` (string), `preview` и `full` — метаданные.
`image.preview`, `image.full`	object	Метаданные: `size_bytes` (int или null), `checksum_sha256` (string или null).
`zip`	object	При наличии архива: `download_url` (string), `size_bytes` (int или null), `checksum_sha256` (string или null).

Ссылки подписаны и действуют 1 час; их можно использовать многократно до истечения срока.
По ссылке доступны файлы опубликованных рулонов.
checksum_sha256 может быть null, пока метаданные файла не рассчитаны; size_bytes содержит размер файла.