Личные подборки пользователей. Могут быть разных типов - произведения ("Буду читать", "Жду перевод", "Любимая детская фантастика" и прочие), издания - "Хочу приобрести", "Куплю", "Лужат на даче" и пр.) и подборки фильмов.
Запрос
GET /user/{user_id}/bookcases
Отображаются список публичных книжных полок пользователя
Параметры
user_id - id пользователя
Пример
https://api.fantlab.ru/user/2/bookcases - список публичных полок юзера "Р.Букашка" (user_id 2)
Ответ
[
{
"bookcase_comment": String|null, # Комментарий (описание) полки
"bookcase_group": String, # Тип книжной полки из списка (free, sale, buy, read, wait)
"bookcase_id": Int, # id книжной полки
"bookcase_name": String, # Название полки
"bookcase_shared": Int, # Тип полки: 0 - закрытая, 1 - публичная
"bookcase_type": String, # Тип книжной полки из списка (work, edition, film)
"date_of_add": DateTime, # Дата добавления в формате: "2011-04-23 15:59:50"
"date_of_add_iso": DateTime, # Дата добавления в формате: "2011-04-23T15:59:50+03"
"date_of_edit": DateTime|null, # Дата последнего редактирования в формате: "2011-04-23 15:59:50"
"date_of_edit_iso": DateTime|null, # Дата последнего редактирования в формате: "2011-04-23T15:59:50+03"
"item_count": Int, # Количество элементов на полке
"sort": Int # Порядковый номер при сортировке
},
...
]
Запрос
GET /user/{user_id}/bookcase/{bookcase_id}?offset={offset}
Не требует авторизации, но при попытке получить содержимое закрытой полки вернется ошибка. Метод используется для получения содержимого полок всех типов, но ответ будет отличаться для разных типов.
Параметры
user_id - id пользователя
bookcase_id - id книжной полки
offset - смещение от начала (не обязательный, по у)
Пример
https://api.fantlab.ru/user/2/bookcase/8180 - одна полка (bookcase_id 8180) юзера"Р.Букашка" (user_id 2)
Ответ для полки с произведениями:
{
bookcase_id: Int, # id книжной полки
bookcase_items: [ | null # содержимое
{
bookcase_item_id: Int, # id item-а книжной полки (счетчик)
item_id: Int, # id произведения
item_comment: String|null, # комментарий
name: String, # название произведения
rusname: String # русскоязычное название произведения
autor_name: String|null, # комбинированная строка с авторами
ext: { # карточка произведения с полной информацией
...
}
},
...
],
bookcase_type: String, # тип книжной полки
count: Int, # количество item-ов на книжной полке
current_page: Int|null, # номер текущей страницы (если null, то первая)
offset: Int, # смещение
offset_h: Int, # верхняя граница смещения
page_count: Int # номер текущей страницы
}
Ответ для полки с изданиями (отличается только структура bookcase_items):
{
...
bookcase_items: [ | null # содержимое
{
autors: String, # авторы издания
bookcase_item_id: Int, # id item-а книжной полки
edition_id: Int, # id издания
item_comment: String|null, # комментарий
name: String, # название издания
publisher: String, # издатель
year: Int # год издания
ext: { # карточка издания с полной информацией
...
}
},
...
],
...
}
Ответ для полки с фильмами (отличается только структура bookcase_items):
{
...
bookcase_items: [ | null # содержимое
{
bookcase_item_id: Int, # id item-а книжной полки
country: String, # страна
director: String, # режиссер(ы) фильма
film_id: Int, # id фильма
item_comment: String|null, # комментарий
name: String, # название фильма
rusname: String, # русскоязычное название фильма
year: Int # год выпуска
ext: { # карточка фильма с полной информацией
...
}
},
...
],
...
}
Персонализированные авторизованные запросы для работы пользователя со своими личными полками просходит в роут-зоне /my/bookcases/* "/my/" - зона API, выделенная для работы пользователям со своими личными данными. Тут, в отличие от роутов библиобазы, при построении урлов используется более классическая логика "items/id/action" и множественное число
Запрос
AUTH POST /my/bookcases/add?name={name}&type={work|edition|film}&shared={on|off}&comment={comment}
Требует авторизации (передачи аутентификационного заголовка или кука в запросе)
Параметры
name - название полки
type - тип полки (work - произведения, edition - издания, film - фильмы)
shared - открытая полка (on) или нет (off)
comment - текст комментария к книжной полке
Пример
POST //api.fantlab.ru/my/bookcases/add?name=Test%20bookcase&type=work&shared=0&comment=Test%20comment
Ответ
id новосозданной книжной полки
Примечание: содержимое полки в запросе передать нельзя. Предполагается, что элементы будут добавляться пользователем по одному вручную.
Запрос
AUTH POST /my/bookcases/{bookcase_id}/edit?name={name}&type={work|edition|film}&shared={on|off}&comment={comment}
Требует авторизации (передачи аутентификационного заголовка или кука в запросе)
Параметры
bookcase_id - id книжной полки для редактирования (передаваемый пользователь должен быть владельцем этой полки)
name - название полки
type - тип полки (work - произведения, edition - издания, film - фильмы)
shared - открытая полка (on) или нет (off)
comment - текст комментария к книжной полке
Пример
POST //api.fantlab.ru/my/bookcases/11945/edit?name=Test%20bookcase&type=work&shared=0&comment=Test%20comment
Ответ
1 в случае успешного завершения
Запрос
AUTH DELETE /my/bookcases/{bookcase_id}/delete
Требует авторизации (передачи аутентификационного заголовка или кука в запросе)
Параметры
bookcase_id - id книжной полки для редактирования (передаваемый пользователь должен быть владельцем этой полки)
Пример
DELETE //api.fantlab.ru/my/bookcases/186919/delete
Ответ
1 в случае успешного завершения
Запрос
AUTH GET /my/bookcases/{bookcase_id}/items?offset={offset}
Требует авторизации (передачи аутентификационного заголовка или кука в запросе) В отличие от запроса для неавторизованного отдаются все полки (открытые и закрытые). Метод используется для получения содержимого полок всех типов, но ответ будет отличаться для разных типов. Но при попытке просмотреть полку с владельцем, не совпадающим с переданным, вернется ошибка.
Параметры
bookcase_id - id полки
offset - смещение от начала
Пример
Ответ для полки с произведениями:
Идентичен ответу для неавторизованного
Запрос
AUTH POST /my/bookcases/{bookcase_id}/items/{item_id}/add # добавить на полку 1 позицию
AUTH POST /my/bookcases/{bookcase_id}/items/{item_id}/delete # убрать с полки 1 позицию
Требует авторизации (передачи аутентификационного заголовка или кука в запросе).
Параметры
item_id - id элемента (произведения, издания или фильма)
bookcase_id - id книжной полки
Пример
POST api.fantlab.ru/my/bookcases/3056/items/1/add - добавить "Гиперион" Дэна Симмонса на книжную полку с id = 3056
Ответ
Количество элементов на полке после изменения
Запрос
AUTH POST /my/bookcases/{bookcase_id}/items/{item_id}/editcomm?txt={comment}
Требует авторизации (передачи аутентификационного заголовка или кука в запросе)
Параметры
bookcase_id - id книжной полки
item_id - id item'а
txt - комментарий
Пример
POST /my/bookcases/123/items/456/editcomm?txt=Отдал%20Васе
Ответ
1 в случае успеха
Запрос
AUTH GET /my/bookcases/
Требует авторизации (передачи аутентификационного заголовка или кука в запросе) В отличие от списка для неавторизованного отдаются все полки (открытые и закрытые)
Параметры
user_id - id пользователя
Пример
Ответ
Идентичен ответу на запрос полок для неавторизованного пользователя
Запрос
AUTH GET /my/bookcases/{bookcase_id}/description
Требует авторизации (передачи аутентификационного заголовка или кука в запросе) В отличие от запроса для неавторизованного отдаются все полки (открытые и закрытые). Метод используется для получения информации о конкретной полке пользователя. Соответственно выдача идентична выдачи при получении всех полок. При попытке просмотреть полку с владельцем, не совпадающим с переданным, вернется ошибка.
Параметры
bookcase_id - id полки
Пример
Ответ
Идентичен ответу для получения всех полок пользователя, только отдается конкретный json объект, соответствующий запрошенной полке
Используются для вывода список полок юзера в карточке базы.
Запрос
AUTH GET /my/bookcases/type/{type}/{item_id}
Требует авторизации (передачи аутентификационного заголовка или кука в запросе) Возвращает список всех полок пользователя данного типа с признаком, присутствует ли данный элемент на этой полке (используются для показа списка полок в карточке - сразу список полок юзера и в каких подборках данных элемент есть)
Параметры
item_id - id item'а
type - тип полки (work|edition|film)
Пример
https://api.fantlab.ru/my/bookcases/type/edition/281 - список полок типа "издания" с проверкой наличиия на них edition281
Ответ (список полок)
[
{
"bookcase_id": Int, # id книжной полки
"bookcase_name": String, # Название полки
"item_added": Int, # Возвращается 1, если элемент присутствует на данной полке, и 0, если нет
},
...
]