├── Docs ├── auth.md ├── author.md ├── awards.md ├── bookcases.md ├── config.md ├── dictor.md ├── edition.md ├── forum.md ├── marks.md ├── news.md ├── oauth.md ├── other.md ├── private-messages.md ├── publisher.md ├── pubnews.md ├── recommendations.md ├── responses.md ├── search-blogs.md ├── search-forum.md ├── search-ids.md ├── search.md ├── subscriptions.md ├── terms.md ├── translator.md ├── user.md └── work.md ├── History.md ├── LICENSE ├── README.md └── Scheme ├── 08365A56-B1B2-4914-95B1-A05BF710A533.png ├── FL Sections Schema.html ├── FL Sections Schema.md └── FL Sections Schema.png /Docs/auth.md: -------------------------------------------------------------------------------- 1 | # Авторизация 2 | 3 | ## Основная авторизация 4 | Запрос 5 | ``` 6 | POST /login 7 | ``` 8 | 9 | Параметры 10 | ``` 11 | login - логин пользователя 12 | password - пароль пользователя 13 | ``` 14 | 15 | Ответ 16 | ``` 17 | # при успешной авторизации 18 | { 19 | auth: Boolean, # состояние авторизации юзера на сайте (да/нет), 1 - при успешной авторизации 20 | user_id: Int, # id юзера 21 | user_login: String, # логин юзера 22 | X-Session: String, # код сессии (например: "Z5RrvohMG2v56xph"), 23 | } 24 | 25 | # при неудаче 26 | { 27 | auth: Boolean, # 0 - при отсутствии авторизации 28 | error_msg: String, # сообщение о причине отказа в авторизации 29 | } 30 | ``` 31 | 32 | Возможные варианты `error_msg`: 33 | - `Пустое значение у логина или пароля` 34 | - `Авторизация с этими логином и паролем не удалась` 35 | 36 | При успешной авторизации будет выдан уникальный код-ключ сессии (токен) "X-Session", который нужно будет добавлять в хедер при запросах к авторизованным ресурсам сайта (В запросах к json общего доступа, без авторизации, этот хиддер игнорируется): 37 | ``` 38 | X-Session: Z5RrvohMG2v56xph 39 | ``` 40 | 41 | **Другой вариант получение ключа сессии** - через cookie: 42 | Также - при успешной авторизации `POST /login` отдается хэдер *Set-Cookie* с куком *fl_s*. (Если он отсутствует при ответе, значит, авторизация не удалась. Значения куки `fl_s` и `X-Session` - одинаковы) 43 | Пример: 44 | ``` 45 | Set-Cookie: fl_s=Z5RrvohMG2v56xph; expires=Mon, 30 Jul 2019 06:46:11 GMT; domain=.fantlab.ru; 46 | ``` 47 | Срок валидности данного кука равен 1 году. Для подписи запросов следует подставлять его в хэдер _Cookie_. В данном случае 48 | ``` 49 | fl_s=Z5RrvohMG2v56xph 50 | ``` 51 | 52 | ## Статус авторизации 53 | 54 | Запрос 55 | ``` 56 | GET /login 57 | ``` 58 | 59 | Параметры 60 | ``` 61 | Заголовок *X-Session* (или кук *fl_s*) c кодом авторизированной сессии. 62 | ``` 63 | 64 | Пример 65 | > [/login](https://api.fantlab.ru/login) - текущий статус авторизации на ФЛ (ваш) 66 | 67 | Ответ 68 | ``` 69 | { 70 | auth: Boolean, # состояние авторизации юзера на сайте (да/нет) 71 | } 72 | ``` 73 | _Примечание: в состоянии авторизации дополнительно отдаются поля `user_id`, `user_login` и `X-Session` (как в примере овтета на POST выше)._ 74 | 75 | --- 76 | 77 | **Примечания про работы с cookie в Android:** При авторизации следует отключить автоматический редирект в HttpClient'е, иначе произойдет перенаправление на главную сайта, а там хэдера _Set-Cookie_ уже нет. В _Retrofit_ это можно сделать при первоначальном конфигурировании: 78 | ```java 79 | httpClientBuilder.setFollowRedirects(false) 80 | ``` 81 | В _Fuel_ чуть сложнее: 82 | ```kotlin 83 | FuelManager.instance.apply { 84 | removeAllResponseInterceptors() 85 | addResponseInterceptor(validatorResponseInterceptor(200..299)) 86 | } 87 | ``` 88 | -------------------------------------------------------------------------------- /Docs/author.md: -------------------------------------------------------------------------------- 1 | # Авторы 2 | 3 | ## Список авторов 4 | Запрос 5 | ``` 6 | GET /autors/{X} 7 | ``` 8 | Параметры 9 | ``` 10 | X - код заглавной буквы (в кодировке Windows-1251) фамилии автора на русском языке 11 | ``` 12 | Пример 13 | ``` 14 | GET /autors/192 - список всех открытых авторов на букву "A" 15 | ``` 16 | Альтернативный запрос для получения всего списка 17 | ``` 18 | GET /autorsall 19 | ``` 20 | Ответ 21 | ``` 22 | { 23 | list:[ 24 | { 25 | type: String # тип сегмента (в данном случае всегда autor) 26 | id: Int, # id автора 27 | url: Url # ссылка на страницу автора 28 | autor_id: Int, # id автора 29 | is_fv: Boolean, # является ли автор фантастоведом 30 | fantastic: Int, # уровень "фантастичности" (0 - не фантаст, 1 - есть фантастические произведения, 2 - фантаст) 31 | country: String, # страна 32 | name: String, # имя на русском языке 33 | name_orig: String, # имя на языке оригинала 34 | name_rp: String, # имя на русском языке в родительном падеже 35 | name_short: String, # имя на русском языке для перечислений (сначала фамилия, затем имя) 36 | }, 37 | ... 38 | ], 39 | liter: String, # по какой заглавной букве фамилии ищем 40 | liter_code: Int|null, # код заглавной буквы фамилии (в кодировке Windows-1251) 41 | liter_list: String # список ссылок на побуквенные списки авторов 42 | } 43 | ``` 44 | Замечания: 45 | 1. В списке только открытые авторы, параметра для получения списка всех авторов нет 46 | 47 | 48 | # Автор 49 | 50 | ## Основная информация 51 | ``` 52 | GET /autor/{id} 53 | ``` 54 | 55 | Пример: 56 | > [/autor/1](https://api.fantlab.ru/autor/1) - Дэн Симменс 57 | 58 | 59 | Ответ: 60 | ``` 61 | { 62 | type: String # тип сегмента (в данном случае всегда autor) 63 | id: Int, # id автора 64 | autor_id: Int, # id автора (дубль, название переменной с типом) 65 | url: Url # ссылка на страницу автора 66 | last_modified: DateTime, # дата последнего редактирования 67 | last_modified_iso: DateTime, # дата последнего редактирования в ISO 8601 68 | 69 | is_opened: Boolean, # открыта ли страница автора 70 | anons: String, # краткий анонс биографии 71 | birthday: Date|null, # дата рождения 72 | country_id: Int|null, # id страны 73 | country_name: String, # название страны 74 | deathday: Date|null, # дата смерти 75 | fantastic: Int, # ? 76 | image: String, # ссылка на основное фото автора 77 | image_preview: String, # ссылка на превью основного фото автора 78 | name: String, # имя на русском языке 79 | name_orig: String, # имя в оригинале 80 | name_pseudonyms: [ # список псевдонимов 81 | ...: String|null, 82 | ... 83 | ], 84 | name_rp: String, # имя на русском языке в родительном падеже 85 | name_short: String, # имя на русском языке для перечислений (сначала фамилия, затем имя) 86 | sex: String, # пол ("m" - мужской, "f" - женский) 87 | stat: { # статистика 88 | awardcount: Int|null, # [any] количество наград 89 | editioncount: Int, # количество изданий 90 | markcount: Int, # количество поставленных автору оценок 91 | moviecount: Int, # количество фильмов (экранизаций и т.д.) 92 | responsecount: Int, # количество написанных на произведения автора отзывов 93 | workcount: Int|null # [any] количество произведений 94 | }, 95 | sites: [ |null # [any] сайты автора 96 | { 97 | descr: String, # описание ссылки 98 | site: String # ссылка 99 | }, 100 | ... 101 | ], 102 | } 103 | ``` 104 | 105 | ## Расширенная информация 106 | ``` 107 | GET /autor/{id}/extended 108 | ``` 109 | в расширенной информации о произведении добавляются блоки: 110 | *biography - биография 111 | classificatory - жанровая классификация 112 | analogs - подборка аналогичных авторов (по классификации) 113 | awards - наград 114 | la_resume - лингвоанализ 115 | biblio_blocks - библиография (список произведений) 116 | sort - вариант сортировки библиографии (необязательный) 117 | / year - по году публикации 118 | / rating - по рейтингу 119 | / markcount - по количеству оценок 120 | / rusname - по русскому названию 121 | / name - по оригинальному названию 122 | / writeyear - по году написания* 123 | 124 | Пример: 125 | > [/autor/1/extended](https://api.fantlab.ru/autor/1/extended) - Дэн Симменс 126 | 127 | *Есть поддержка запроса с получением частичных данных - с указанием параметров и сортировки: 128 | > /autor/1?biography=1&awards=1&&biblio_blocks=1&sort=rating* 129 | 130 | Ответ 131 | ``` 132 | { 133 | id: Int, # id автора 134 | ... все поля обычной карточки автора (см. выше) и добаляются новые: ... 135 | 136 | biography: String|null, # [biography] биография 137 | biography_notes: String|null, # [any] примечания к биографии 138 | source: String|null, # [any] описание источника биографии 139 | source_link: String|null, # [any] ссылка на источник биографии 140 | 141 | compiler: String|null, # [any] составитель библиографии 142 | curator: Int|null, # id куратора библиографии 143 | 144 | la_resume: [ |null # [la_resume] лингвоанализ 145 | ...: String, # отдельный пункт анализа 146 | ... 147 | ], 148 | registered_user_id: Int|null, # id автора как пользователя Fantlab'а (если зарегистрирован) 149 | registered_user_login: String|null, # логин автора как пользователя Fantlab'а, 150 | 151 | awards: { |null # [awards] список наград 152 | nom: [ 153 | { 154 | award_icon: String, # ссылка на логотип премии 155 | award_id: Int, # id премии 156 | award_in_list: Int, # ? 157 | award_is_opened: Boolean, # открыта ли страница премии 158 | award_name: String, # название премии 159 | award_rusname: String, # русскоязычное название премии 160 | contest_id: Int, # id конкурса 161 | contest_name: String, # название конкурса (обычно сопадает с годом) 162 | contest_year: Int, # год проведения конкурса 163 | cw_id: Int, # ? 164 | cw_is_winner: Int, # ? 165 | cw_postfix: String, # ? 166 | cw_prefix: String, # ? 167 | nomination_id: Int|null, # id номинации 168 | nomination_name: String|null, # название номинации 169 | nomination_rusname: String|null, # русскоязычное название номинации 170 | work_id: Int|null, # id награжденного произведения (null, если награда относится к автору) 171 | work_name: String|null, # название награжденного произведения (null, если награда относится к автору) 172 | work_rusname: String|null, # русскоязычное название награжденного произведения (null, если награда относится к автору) 173 | work_year: Int|null # год публикации произведения (null, если награда относится к автору) 174 | }, 175 | ... 176 | ], 177 | win: [ 178 | { 179 | ... # те же самые поля 180 | }, 181 | ... 182 | ] 183 | }, 184 | 185 | classificatory: { # жарны и классификар произведений автора 186 | ... # формат массива аналогичен выдаче {classificatory} в карточке произведения 187 | } 188 | 189 | analogs: [ # подборка похожих писателей (по классификатору) 190 | { 191 | autor2_id: Int, # id автора 192 | midmark: Float, # ср. оценка произведений автора (рейтинг автора) 193 | rusname: String, # русскоязычное имя автора 194 | }, 195 | ... 196 | ], 197 | 198 | cycles_blocks: { |null # [biblio_blocks] блок циклов 199 | {block_id}: { # id блока (см. константы) 200 | id: Int, # id блока (совпадает с block_id) 201 | list: [ # список циклов в блоке 202 | { 203 | authors: [ # список авторов 204 | { 205 | id: Int, # id автора 206 | name: String, # русскоязычное имя автора 207 | type: String # тип автора (autor|art) 208 | }, 209 | ... 210 | ], 211 | children: [ # список произведений, входящих в цикл 212 | { 213 | authors: [ # список авторов 214 | { 215 | id: Int, # id автора 216 | name: String, # русскоязычное имя автора 217 | type: String # тип автора (autor|art) 218 | }, 219 | ... 220 | ], 221 | deep: Int, # глубина вложенности 222 | plus: ?|null, # доп. произведение [с "плюсом"] или нет 223 | public_download_file: Boolean, # доступен ли файл с текстом для скачивания 224 | publish_status: String, # статус публикации 225 | rating: { 226 | rating: Float, # рейтинг 227 | voters: Int, # количество голосов 228 | }, 229 | val_midmark: Float|null, # простое среднее по оценкам (эта цифра видна только в Рейтинг -> Подробнее) 230 | val_midmark_by_weight: Float|null, # рейтинг произведения 231 | val_midmark_rating: Float|null, # ? 232 | val_rating: Float|null, # ? (совпадает с val_midmark_rating) 233 | val_responsecount: Int|null, # количество отзывов на произведение 234 | val_voters: Int|null, # количество голосов в рейтинге 235 | work_id: Int, # id произведения 236 | work_lp: Int, # ? 237 | work_name: String, # русскоязычное название произведения 238 | work_name_alt: String, # альтернативные названия 239 | work_name_bonus: String, # ? 240 | work_name_orig: String, # название произведения в оригинале 241 | work_notfinished: Boolean, # произведение не закончено? 242 | work_preparing: Boolean, # произведение в планах? 243 | work_published: Boolean, # произведение опубликовано? 244 | work_root_saga: [ # список "родительских" произведений 245 | { 246 | prefix: String, # степень отношения произведения к "родителю" (например, "входит в ") 247 | work_id: Int, # id произведения 248 | work_name: String, # русскоязычное название произведения 249 | work_type: String, # тип произведения 250 | work_type_id: Int, # id типа произведения 251 | work_type_in: String # ? 252 | }, 253 | ... 254 | ], 255 | work_type: String, # тип произведения 256 | work_type_icon: String, # иконку какого типа произведений показывать 257 | work_type_id: Int, # id типа произведения 258 | work_type_name: String, # название типа произведения 259 | work_year: ?|null, # год публикации 260 | work_year_of_write: ?|null # год написания 261 | }, 262 | ... 263 | ] 264 | position_index: Int|null, # ? 265 | position_is_node: Int, # ? 266 | position_level: Int, # ? 267 | position_show_in_biblio: Int, # ? 268 | position_show_subworks_in_biblio: Int, # ? 269 | public_download_file: Boolean, # доступен ли файл с текстом для скачивания 270 | publish_status: String, # статус публикации 271 | rating: { 272 | rating: Float, # рейтинг 273 | voters: Int, # количество голосов 274 | }, 275 | val_midmark: Float|null, # простое среднее по оценкам (эта цифра видна только в Рейтинг -> Подробнее) 276 | val_midmark_by_weight: Float|null, # рейтинг произведения 277 | val_midmark_rating: Float|null, # ? 278 | val_rating: Float|null, # ? (совпадает с val_midmark_rating) 279 | val_responsecount: Int|null, # количество отзывов на произведение 280 | val_voters: Int|null, # количество голосов в рейтинге 281 | work_id: Int, # id произведения 282 | work_lp: Int, # ? 283 | work_name: String, # русскоязычное название произведения 284 | work_name_alt: String, # альтернативные названия 285 | work_name_bonus: String, # ? 286 | work_name_orig: String, # название произведения в оригинале 287 | work_notfinished: Boolean, # произведение не закончено? 288 | work_preparing: Boolean, # произведение в планах? 289 | work_published: Boolean, # произведение опубликовано? 290 | work_root_saga: null, # список "родительских" произведений 291 | work_type: String, # тип произведения 292 | work_type_icon: String, # иконку какого типа произведений показывать 293 | work_type_id: Int, # id типа произведения 294 | work_type_name: String, # название типа произведения 295 | work_year: ?|null, # год публикации 296 | work_year_of_write: ?|null # год написания 297 | }, 298 | ... 299 | ], 300 | name: String, # категория блока 301 | title: String # русскоязычное название блока 302 | }, 303 | ... 304 | }, 305 | works_blocks: { |null # [biblio_blocks] блок отдельных произведений 306 | {block_id}: { # id блока (см. константы) 307 | id: Int, # id блока (совпадает с block_id) 308 | list: [ # список произведений в блоке 309 | { 310 | authors: [ # список авторов 311 | { 312 | id: Int, # id автора 313 | name: String, # русскоязычное имя автора 314 | type: String # тип автора (autor|art) 315 | }, 316 | ... 317 | ], 318 | position_index: Int|null, # ? 319 | position_is_node: Int, # ? 320 | position_level: Int, # ? 321 | position_show_in_biblio: Int, # ? 322 | position_show_subworks_in_biblio: Int, # ? 323 | public_download_file: Boolean, # доступен ли файл с текстом для скачивания 324 | publish_status: String, # статус публикации 325 | rating: { 326 | rating: Float, # рейтинг 327 | voters: Int, # количество голосов 328 | }, 329 | val_midmark: Float|null, # простое среднее по оценкам (эта цифра видна только в Рейтинг -> Подробнее) 330 | val_midmark_by_weight: Float|null, # рейтинг произведения 331 | val_midmark_rating: Float|null, # ? 332 | val_rating: Float|null, # ? (совпадает с val_midmark_rating) 333 | val_responsecount: Int|null, # количество отзывов на произведение 334 | val_voters: Int|null, # количество голосов в рейтинге 335 | work_id: Int, # id произведения 336 | work_lp: Int, # ? 337 | work_name: String, # русскоязычное название произведения 338 | work_name_alt: String, # альтернативные названия 339 | work_name_bonus: String, # ? 340 | work_name_orig: String, # название произведения в оригинале 341 | work_notfinished: Boolean, # произведение не закончено? 342 | work_preparing: Boolean, # произведение в планах? 343 | work_published: Boolean, # произведение опубликовано? 344 | work_root_saga: [ # список "родительских" произведений 345 | { 346 | prefix: String, # степень отношения произведения к "родителю" (например, "входит в ") 347 | work_id: Int, # id произведения 348 | work_name: String, # русскоязычное название произведения 349 | work_type: String, # тип произведения 350 | work_type_id: Int, # id типа произведения 351 | work_type_in: String # ? 352 | }, 353 | ... 354 | ], 355 | work_type: String, # тип произведения 356 | work_type_icon: String, # иконку какого типа произведений показывать 357 | work_type_id: Int, # id типа произведения 358 | work_type_name: String, # название типа произведения 359 | work_year: ?|null, # год публикации 360 | work_year_of_write: ?|null # год написания 361 | }, 362 | ... 363 | ], 364 | name: String, # категория блока 365 | title: String # русскоязычное название блока 366 | }, 367 | ... 368 | } 369 | } 370 | ``` 371 | 372 | 373 | ## Список изданий 374 | Запрос 375 | ``` 376 | GET /autor/{id}/alleditions?editions_blocks={0|1} 377 | ``` 378 | Параметры 379 | ``` 380 | id - id автора 381 | editions_blocks - выводить ли сам список изданий (необязательный; по-умолчанию 0) 382 | ``` 383 | Пример 384 | ``` 385 | GET /autor/133/alleditions?editions_blocks=1 - список всех изданий Джорджа Р.Р. Мартина 386 | ``` 387 | Ответ 388 | ``` 389 | { 390 | editions_blocks: { |null # [editions_blocks] список изданий 391 | {id}: { # id блока (список практически совпадает с editions_info -> booktype -> type) 392 | block: String, # категория блока 393 | id: Int, # id блока 394 | list: [ # список изданий в данном блоке 395 | { 396 | autors: String, # авторы 397 | compilers: String, # составители 398 | correct_level: Float, # уровень проверенности издания (0 - не проверено, 0.5 - проверено не полностью, 1 - проверено) 399 | cover_type: Int, # id типа обложки 400 | ebook: Boolean, # электронная книга или нет 401 | edition_id: Int, # id издания 402 | fiction: Int, # ? 403 | lang: String, # русскоязычное название языка 404 | lang_code: String, # код языка 405 | lang_id: Int, # id языка 406 | name: String, # название издания 407 | pic_num: Int, # ? 408 | plandate: ?|null, # ? 409 | plandate_txt: String, # пояснение насчет планируемой даты 410 | translators: Int|null, # id переводчика 411 | type: Int, # id типа издания 412 | year: Int # год издания 413 | }, 414 | ... 415 | ], 416 | name: String, # название блока 417 | title: String # русскоязычное название блока 418 | }, 419 | ... 420 | }, 421 | editions_info: { # сводная информация об изданиях 422 | all: Int, # количество всех изданий 423 | booktype: { # статистика по типу издания 424 | {type}: { |null # тип издания (см. константы) 425 | count: Int, # количество изданий данного типа 426 | id: Int, # id типа издания (равен type) 427 | name: String, # название типа 428 | title: String # русскоязычное название типа 429 | }, 430 | ... 431 | }, 432 | langs: { # статистика по языку издания 433 | {lang}: { |null # язык издания (см. константы) 434 | count: Int, # количество изданий на данном языке 435 | lang_code: String, # код языка 436 | lang_id: Int, # id языка (равен lang) 437 | lang_name: String # русскоязычное название языка 438 | }, 439 | ... 440 | }, 441 | translators: [ # статистика по переводчикам 442 | { 443 | count: Int, # количество изданий с данным переводчиком 444 | id: Int, # id переводчика 445 | name: String # имя переводчика 446 | } 447 | ] 448 | }, 449 | stat: { 450 | editioncount: Int # количество всех изданий 451 | }, 452 | title: String # ссылка на страницу автора (используется на вебе) 453 | } 454 | ``` 455 | 456 | 457 | ## Список отзывов на произведения 458 | см. [Docs/responses.md#Отзывы на все произведения автора](../Docs/responses.md#Отзывы-на-все-произведения-автора) 459 | 460 | 461 | ## Список наград отдельно 462 | Запрос 463 | ``` 464 | GET /autor/{id}/awards?sort={byorder|byaward|bychrono|bywork} 465 | ``` 466 | Параметры 467 | ``` 468 | id - id автора 469 | sort - вариант сортировки наград (необязательный; по-умолчанию bychrono) 470 | * byorder - по порядку 471 | * byaward - по премиям 472 | * bychrono - по хронологии 473 | * bywork - по произведениям 474 | ``` 475 | Пример 476 | ``` 477 | GET /autor/133/awards?sort=bywork - награды Дж. Р.Р. Мартина, осортированные по произведениям 478 | ``` 479 | Ответ 480 | ``` 481 | [ 482 | { 483 | ... # те же самые поля, что и в autor -> awards 484 | } 485 | ] 486 | ``` 487 | **Nota bene** 488 | 489 | список отдается без разбиения по категориям 490 | -------------------------------------------------------------------------------- /Docs/awards.md: -------------------------------------------------------------------------------- 1 | # Премии 2 | ## Список премий 3 | Запрос 4 | ``` 5 | GET /awards?nonfant={0|1}&sort={name|country|type|lang} 6 | ``` 7 | Параметры 8 | ``` 9 | nonfant - показывать ли нефантастические премии (необязательный; по-умолчанию 0) 10 | sort - вариант сортировки (необязательный; по-умолчанию lang) 11 | * name - по названию 12 | * country - по стране 13 | * type - по типу 14 | * lang - по языку 15 | ``` 16 | Пример 17 | ``` 18 | GET /awards?nonfant=1&sort=country - вывести список всех премий, отсортированный по странам 19 | ``` 20 | Ответ 21 | ``` 22 | [ 23 | { 24 | award_close: Boolean, # закрыта ли премия 25 | award_id: Int, # id премии 26 | award_type: Int, # ? 27 | contests_count: Int, # количество конкурсов 28 | country_id: Int, # id страны 29 | country_name: String, # страна 30 | description_length: Int, # длина описания (в символах) 31 | homepage: String, # ссылка на официальный сайт премии 32 | is_opened: Boolean, # открыта ли страница премии 33 | lang_id: Int, # id языка премии 34 | lang_name: String, # язык премии 35 | max_date: Date, # дата последнего на данный момент конкурса 36 | min_date: Date, # дата первого конкурса 37 | name: String, # название в оригинале 38 | nomi_count: Int, # количество номинаций 39 | non_fantastic: Boolean, # нефантастическая премия? 40 | rusname: String, # русскоязычное название 41 | show_in_list: Boolean # ? 42 | }, 43 | ... 44 | ] 45 | ``` 46 | Замечания: 47 | 1. Разделения по категориям в выдаче нет. То есть, скажем, при сортировке по языку в выдаче нет категорий "английский язык", "русский язык" и пр., все премии перечислены одним списком 48 | ## Премия 49 | Запрос 50 | ``` 51 | GET /award/{id}?include_nomi={0|1}&include_contests={0|1}&sort={contest|nomi} 52 | ``` 53 | Параметры 54 | ``` 55 | id - id премии 56 | include_nomi - показывать ли информацию о номинациях (необязательный; по-умолчанию 0) 57 | include_contests - показывать ли информацию о конкурсах (необязательный; по-умолчанию 0) 58 | sort - вариант сортировки (необязательный; по-умолчанию contest) 59 | * contest - по году 60 | * nomi - по номинациям 61 | ``` 62 | Пример 63 | ``` 64 | GET /award/2?include_nomi=1&include_contests=1&sort=nomi - выдать всю информацию о Хьюго с сорировкой результатов по номинациям 65 | ``` 66 | Ответ 67 | ``` 68 | { 69 | award_close: Boolean, # закрыта ли премия 70 | award_id: Int, # id премии 71 | award_type: Int, # ? 72 | comment: String, # комментарий 73 | compiler: String, # ? 74 | contests: [ |null # [include_contests] список конкурсов (см. ниже) 75 | ... 76 | ], 77 | copyright: String, # ? 78 | copyright_link: String, # ? 79 | country_id: Int, # id страны 80 | country_name: String, # страна 81 | curator_id: Int, # id куратора премии 82 | description: String, # описание (могут присутствовать bb-теги) 83 | homepage: String, # ссылка на официальный сайт премии 84 | is_opened: Boolean, # открыта ли страница премии 85 | lang_id: Int, # id языка 86 | max_date: Date, # дата последнего на данный момент конкурса 87 | min_date: Date, # дата первого конкурса 88 | name: String, # название в оригинале 89 | nominations: [ |null # [include_nomi] список номинаций 90 | { 91 | book_count: Int, # количество номинированных позиций за все время существования премии 92 | description: String, # описание 93 | description_length: Int, # длина описания (в символах) 94 | name: String, # название номинации в оригинале 95 | nomination_id: Int, # id номинации 96 | number: Int, # порядковый номер номинации 97 | rusname: String # русскоязычное название номинации 98 | }, 99 | ... 100 | ], 101 | non_fantastic: Boolean, # нефантастическая премия? 102 | notes: String, # примечания 103 | process_status: String, # ? 104 | rusname: String, # русскоязычное название 105 | show_in_list: Boolean # ? 106 | } 107 | ``` 108 | Выдача массива *contests* зависит от варианта сортировки. При **sort=contest** выдача полностью совпадает с выдачей [конкурса](contest.md#Конкурс). При **sort=nomi** выдача выглядит следующим образом: 109 | ``` 110 | { 111 | award_id: Int, # id премии 112 | contest_works: [ # список номинантов 113 | ... # выдача номинанта совпадает с contest -> contest_works (см. Конкурс) 114 | ], 115 | name: String, # название номинации в оригинале 116 | nomination_id: Int, # id номинации 117 | rusname: String # русскоязычное название номинации 118 | } 119 | ``` 120 | ## Конкурс 121 | Запрос 122 | ``` 123 | GET /contest/{id}?include_works={0|1} 124 | ``` 125 | Параметры 126 | ``` 127 | id - id конкурса 128 | include_works - выводить ли номинантов (необязательный; по-умолчанию 0) 129 | ``` 130 | Пример 131 | ``` 132 | GET /contest/7955?include_works=1 - Хьюго 2017г. с номинантами 133 | ``` 134 | Ответ 135 | ``` 136 | { 137 | award_id: Int, # id премии 138 | award_name: String, # название премии в оригинале 139 | award_rusname: String, # русскоязычное название премии 140 | contest_id: Int, # id конкурса 141 | contest_works: [ |null # список победителей по номинациям в конкурсе 142 | { 143 | autor_rusname: String, # русскоязычное имя автора 144 | award_opened: Boolean, # открыта ли страница премии 145 | contest_id: Int, # id конкурса 146 | contest_work_id: Int, # id номинанта конкурса 147 | contest_year: Int, # год проведения конкурса 148 | cw_link_id: Int, # id номинанта 149 | cw_link_type: String, # тип номинанта (work, autor и т.д.) (итоговая сслыка: https://fantlab.ru/{cw_link_type}{cw_link_id}) 150 | cw_name: String, # автор + имя/название номинанта в оригинале 151 | cw_number: Int, # ? 152 | cw_postfix: String, # ? 153 | cw_prefix: String, # ? 154 | cw_rusname: String, # русскоязычные автор + имя/название номинанта 155 | cw_winner: Boolean, # победитель (в данном случае всегда 1) 156 | nomination_id: Int, # id номинации 157 | nomination_name: String, # название номинации в оригинале 158 | nomination_number: Int, # порядковый номер номинации 159 | nomination_rusname: String, # русскоязычное название номинации 160 | work_rusname: String # русскоязычное имя/название номинанта 161 | }, 162 | ... 163 | ], 164 | date: Date, # дата проведения конкурса 165 | description: String, # описание конкурса 166 | description_length: Int, # длина описания (в символах) 167 | name: String, # название конкурса в оригинале 168 | name_year: String, # ? 169 | non_winner_count: Int, # ? 170 | number: Int, # ? 171 | place: String, # место проведения 172 | short_description: String # краткое описание 173 | } 174 | ``` 175 | -------------------------------------------------------------------------------- /Docs/bookcases.md: -------------------------------------------------------------------------------- 1 | # Книжные полки 2 | 3 | Личные подборки пользователей. Могут быть разных типов - произведения ("Буду читать", "Жду перевод", "Любимая детская фантастика" и прочие), издания - "Хочу приобрести", "Куплю", "Лужат на даче" и пр.) и подборки фильмов. 4 | 5 | ## Список полок пользователя 6 | Запрос 7 | ``` 8 | GET /user/{user_id}/bookcases 9 | ``` 10 | Отображаются список публичных книжных полок пользователя 11 | 12 | Параметры 13 | ``` 14 | user_id - id пользователя 15 | ``` 16 | 17 | Пример 18 | > https://api.fantlab.ru/user/2/bookcases - список публичных полок юзера "Р.Букашка" (user_id 2) 19 | 20 | Ответ 21 | ``` 22 | [ 23 | { 24 | "bookcase_comment": String|null, # Комментарий (описание) полки 25 | "bookcase_group": String, # Тип книжной полки из списка (free, sale, buy, read, wait) 26 | "bookcase_id": Int, # id книжной полки 27 | "bookcase_name": String, # Название полки 28 | "bookcase_shared": Int, # Тип полки: 0 - закрытая, 1 - публичная 29 | "bookcase_type": String, # Тип книжной полки из списка (work, edition, film) 30 | "date_of_add": DateTime, # Дата добавления в формате: "2011-04-23 15:59:50" 31 | "date_of_add_iso": DateTime, # Дата добавления в формате: "2011-04-23T15:59:50+03" 32 | "date_of_edit": DateTime|null, # Дата последнего редактирования в формате: "2011-04-23 15:59:50" 33 | "date_of_edit_iso": DateTime|null, # Дата последнего редактирования в формате: "2011-04-23T15:59:50+03" 34 | "item_count": Int, # Количество элементов на полке 35 | "sort": Int # Порядковый номер при сортировке 36 | }, 37 | ... 38 | ] 39 | ``` 40 | 41 | ## Содержимое книжной полки (подборки) 42 | 43 | Запрос 44 | ``` 45 | GET /user/{user_id}/bookcase/{bookcase_id}?offset={offset} 46 | ``` 47 | Не требует авторизации, но при попытке получить содержимое закрытой полки вернется ошибка. Метод используется для получения содержимого полок всех типов, но ответ будет отличаться для разных типов. 48 | 49 | Параметры 50 | ``` 51 | user_id - id пользователя 52 | bookcase_id - id книжной полки 53 | offset - смещение от начала (не обязательный, по у) 54 | ``` 55 | 56 | Пример 57 | > https://api.fantlab.ru/user/2/bookcase/8180 - одна полка (bookcase_id 8180) юзера"Р.Букашка" (user_id 2) 58 | 59 | Ответ для полки с произведениями: 60 | ``` 61 | { 62 | bookcase_id: Int, # id книжной полки 63 | bookcase_items: [ | null # содержимое 64 | { 65 | bookcase_item_id: Int, # id item-а книжной полки (счетчик) 66 | item_id: Int, # id произведения 67 | item_comment: String|null, # комментарий 68 | name: String, # название произведения 69 | rusname: String # русскоязычное название произведения 70 | autor_name: String|null, # комбинированная строка с авторами 71 | ext: { # карточка произведения с полной информацией 72 | ... 73 | } 74 | }, 75 | ... 76 | ], 77 | bookcase_type: String, # тип книжной полки 78 | count: Int, # количество item-ов на книжной полке 79 | current_page: Int|null, # номер текущей страницы (если null, то первая) 80 | offset: Int, # смещение 81 | offset_h: Int, # верхняя граница смещения 82 | page_count: Int # номер текущей страницы 83 | } 84 | ``` 85 | 86 | Ответ для полки с изданиями (отличается только структура `bookcase_items`): 87 | ``` 88 | { 89 | ... 90 | bookcase_items: [ | null # содержимое 91 | { 92 | autors: String, # авторы издания 93 | bookcase_item_id: Int, # id item-а книжной полки 94 | edition_id: Int, # id издания 95 | item_comment: String|null, # комментарий 96 | name: String, # название издания 97 | publisher: String, # издатель 98 | year: Int # год издания 99 | ext: { # карточка издания с полной информацией 100 | ... 101 | } 102 | }, 103 | ... 104 | ], 105 | ... 106 | } 107 | ``` 108 | 109 | Ответ для полки с фильмами (отличается только структура `bookcase_items`): 110 | ``` 111 | { 112 | ... 113 | bookcase_items: [ | null # содержимое 114 | { 115 | bookcase_item_id: Int, # id item-а книжной полки 116 | country: String, # страна 117 | director: String, # режиссер(ы) фильма 118 | film_id: Int, # id фильма 119 | item_comment: String|null, # комментарий 120 | name: String, # название фильма 121 | rusname: String, # русскоязычное название фильма 122 | year: Int # год выпуска 123 | ext: { # карточка фильма с полной информацией 124 | ... 125 | } 126 | }, 127 | ... 128 | ], 129 | ... 130 | } 131 | ``` 132 | 133 | --- 134 | 135 | 136 | # Свои полки (авторизированные запросы) 137 | 138 | Персонализированные авторизованные запросы для работы пользователя со своими личными полками просходит в роут-зоне 139 | /my/bookcases/* 140 | "/my/" - зона API, выделенная для работы пользователям со своими личными данными. Тут, в отличие от роутов библиобазы, при построении урлов используется более классическая логика "items/id/action" и множественное число 141 | 142 | 143 | ## Создание книжной полки 144 | Запрос 145 | ``` 146 | AUTH POST /my/bookcases/add?name={name}&type={work|edition|film}&shared={on|off}&comment={comment} 147 | ``` 148 | *Требует авторизации (передачи аутентификационного заголовка или кука в запросе)* 149 | 150 | Параметры 151 | ``` 152 | name - название полки 153 | type - тип полки (work - произведения, edition - издания, film - фильмы) 154 | shared - открытая полка (on) или нет (off) 155 | comment - текст комментария к книжной полке 156 | ``` 157 | 158 | Пример 159 | > POST //api.fantlab.ru/my/bookcases/add?name=Test%20bookcase&type=work&shared=0&comment=Test%20comment 160 | 161 | Ответ 162 | ``` 163 | id новосозданной книжной полки 164 | ``` 165 | Примечание: содержимое полки в запросе передать нельзя. Предполагается, что элементы будут добавляться пользователем по одному вручную. 166 | 167 | 168 | ## Редактирование книжной полки 169 | Запрос 170 | ``` 171 | AUTH POST /my/bookcases/{bookcase_id}/edit?name={name}&type={work|edition|film}&shared={on|off}&comment={comment} 172 | ``` 173 | *Требует авторизации (передачи аутентификационного заголовка или кука в запросе)* 174 | 175 | Параметры 176 | ``` 177 | bookcase_id - id книжной полки для редактирования (передаваемый пользователь должен быть владельцем этой полки) 178 | name - название полки 179 | type - тип полки (work - произведения, edition - издания, film - фильмы) 180 | shared - открытая полка (on) или нет (off) 181 | comment - текст комментария к книжной полке 182 | 183 | ``` 184 | Пример 185 | > POST //api.fantlab.ru/my/bookcases/11945/edit?name=Test%20bookcase&type=work&shared=0&comment=Test%20comment 186 | 187 | Ответ 188 | ``` 189 | 1 в случае успешного завершения 190 | ``` 191 | 192 | 193 | ## Удаление книжной полки 194 | Запрос 195 | ``` 196 | AUTH DELETE /my/bookcases/{bookcase_id}/delete 197 | ``` 198 | *Требует авторизации (передачи аутентификационного заголовка или кука в запросе)* 199 | 200 | Параметры 201 | ``` 202 | bookcase_id - id книжной полки для редактирования (передаваемый пользователь должен быть владельцем этой полки) 203 | ``` 204 | 205 | Пример 206 | > DELETE //api.fantlab.ru/my/bookcases/186919/delete 207 | 208 | Ответ 209 | ``` 210 | 1 в случае успешного завершения 211 | ``` 212 | 213 | 214 | ## Содержимое одной полки авторизованного пользователя 215 | Запрос 216 | ``` 217 | AUTH GET /my/bookcases/{bookcase_id}/items?offset={offset} 218 | ``` 219 | *Требует авторизации (передачи аутентификационного заголовка или кука в запросе)* 220 | В отличие от запроса для неавторизованного отдаются все полки (открытые и закрытые). 221 | Метод используется для получения содержимого полок всех типов, но ответ будет отличаться для разных типов. 222 | Но при попытке просмотреть полку с владельцем, не совпадающим с переданным, вернется ошибка. 223 | 224 | Параметры 225 | ``` 226 | bookcase_id - id полки 227 | offset - смещение от начала 228 | ``` 229 | Пример 230 | > https://api.fantlab.ru/my/bookcases/3056/items 231 | 232 | Ответ для полки с произведениями: 233 | ``` 234 | Идентичен ответу для неавторизованного 235 | ``` 236 | 237 | 238 | ## Добавление или удаление элементов с книжной полки 239 | Запрос 240 | ``` 241 | AUTH POST /my/bookcases/{bookcase_id}/items/{item_id}/add # добавить на полку 1 позицию 242 | AUTH POST /my/bookcases/{bookcase_id}/items/{item_id}/delete # убрать с полки 1 позицию 243 | ``` 244 | *Требует авторизации (передачи аутентификационного заголовка или кука в запросе).* 245 | 246 | Параметры 247 | ``` 248 | item_id - id элемента (произведения, издания или фильма) 249 | bookcase_id - id книжной полки 250 | ``` 251 | Пример 252 | > POST api.fantlab.ru/my/bookcases/3056/items/1/add - добавить "Гиперион" Дэна Симмонса на книжную полку с id = 3056 253 | 254 | Ответ 255 | ``` 256 | Количество элементов на полке после изменения 257 | ``` 258 | 259 | 260 | ## Добавление комментария к item 261 | Запрос 262 | ``` 263 | AUTH POST /my/bookcases/{bookcase_id}/items/{item_id}/editcomm?txt={comment} 264 | ``` 265 | *Требует авторизации (передачи аутентификационного заголовка или кука в запросе)* 266 | 267 | Параметры 268 | ``` 269 | bookcase_id - id книжной полки 270 | item_id - id item'а 271 | txt - комментарий 272 | ``` 273 | 274 | Пример 275 | > POST /my/bookcases/123/items/456/editcomm?txt=Отдал%20Васе 276 | 277 | Ответ 278 | ``` 279 | 1 в случае успеха 280 | ``` 281 | 282 | 283 | ## Список всех полок авторизованного пользователя 284 | Запрос 285 | ``` 286 | AUTH GET /my/bookcases/ 287 | ``` 288 | *Требует авторизации (передачи аутентификационного заголовка или кука в запросе)* 289 | В отличие от списка для неавторизованного отдаются все полки (открытые и закрытые) 290 | 291 | Параметры 292 | ``` 293 | user_id - id пользователя 294 | ``` 295 | 296 | Пример 297 | > https://api.fantlab.ru/my/bookcases 298 | 299 | Ответ 300 | ``` 301 | Идентичен ответу на запрос полок для неавторизованного пользователя 302 | ``` 303 | 304 | ## Информация о конкретной полке авторизованного пользователя 305 | Запрос 306 | ``` 307 | AUTH GET /my/bookcases/{bookcase_id}/description 308 | ``` 309 | *Требует авторизации (передачи аутентификационного заголовка или кука в запросе)* 310 | В отличие от запроса для неавторизованного отдаются все полки (открытые и закрытые). 311 | Метод используется для получения информации о конкретной полке пользователя. Соответственно 312 | выдача идентична выдачи при получении всех полок. При попытке просмотреть полку с владельцем, 313 | не совпадающим с переданным, вернется ошибка. 314 | 315 | Параметры 316 | ``` 317 | bookcase_id - id полки 318 | ``` 319 | Пример 320 | > https://api.fantlab.ru/my/bookcases/3056/description 321 | 322 | Ответ 323 | ``` 324 | Идентичен ответу для получения всех полок пользователя, только отдается конкретный json объект, соответствующий запрошенной полке 325 | ``` 326 | 327 | ## Список полок авторизованного пользователя одного типа + наличие элемента на полках пользователя 328 | *Используются для вывода список полок юзера в карточке базы.* 329 | 330 | Запрос 331 | ``` 332 | AUTH GET /my/bookcases/type/{type}/{item_id} 333 | ``` 334 | *Требует авторизации (передачи аутентификационного заголовка или кука в запросе)* 335 | Возвращает список всех полок пользователя данного типа с признаком, присутствует ли данный элемент на этой полке (используются для показа списка полок в карточке - сразу список полок юзера и в каких подборках данных элемент есть) 336 | 337 | Параметры 338 | ``` 339 | item_id - id item'а 340 | type - тип полки (work|edition|film) 341 | ``` 342 | 343 | Пример 344 | > https://api.fantlab.ru/my/bookcases/type/edition/281 - список полок типа "издания" с проверкой наличиия на них edition281 345 | 346 | Ответ (список полок) 347 | ``` 348 | [ 349 | { 350 | "bookcase_id": Int, # id книжной полки 351 | "bookcase_name": String, # Название полки 352 | "item_added": Int, # Возвращается 1, если элемент присутствует на данной полке, и 0, если нет 353 | }, 354 | ... 355 | ] 356 | 357 | ``` 358 | -------------------------------------------------------------------------------- /Docs/config.md: -------------------------------------------------------------------------------- 1 | # Константы 2 | 3 | Запрос 4 | ``` 5 | GET /config.json 6 | ``` 7 | 8 | Ответ: 9 | ``` 10 | { 11 | film_types: [{ # типы фильмов 12 | id: Int, # id типа 13 | title: String # название 14 | }], 15 | work_types: [{ # типы произведений 16 | id: Int, # id типа 17 | image: Url, # ссылка на заглушку 18 | title: { # название 19 | en: String, # на английском 20 | rus: String # на русском 21 | } 22 | }] 23 | } 24 | ``` 25 | -------------------------------------------------------------------------------- /Docs/dictor.md: -------------------------------------------------------------------------------- 1 | # Диктор 2 | Запрос 3 | ``` 4 | GET /dictor/{id}?biography={0|1}&awards={0|1}&editions={0|1} 5 | ``` 6 | Параметры 7 | ``` 8 | id - id диктора 9 | biography - выводить ли биографию (необязательный; по-умолчанию 0) 10 | awards - выводить ли награды (необязательный; по-умолчанию 0) 11 | editions - выводить ли издания (необязательный; по-умолчанию 0) 12 | ``` 13 | Пример 14 | ``` 15 | GET /dictor/1?biography=1&awards=1&editions=1 - полная информация про диктора Влада Коппа 16 | ``` 17 | Ответ 18 | ``` 19 | { 20 | age: Int, # возраст на данный момент или на момент смерти 21 | anons: String, # анонс биографии 22 | articles: [ # список статей 23 | ...: ?|null 24 | ], 25 | awards: [ |null # [awards] список наград 26 | ...: ?|null 27 | ], 28 | biography: String|null, # [biography] биография (могут присутствовать bb-теги) 29 | biography_notes: String, # примечание к биографии 30 | biography_source: String, # источник биографии 31 | birthday: Date, # дата рождения 32 | countries: [ # список стран 33 | { 34 | country_id: Int, # id страны 35 | name: String # страна 36 | }, 37 | ... 38 | ], 39 | curator_id: Int, # id куратора 40 | curator_name: String, # логин куратора 41 | deathday: Int|null, # дата смерти 42 | editions: [ |null # [editions] список изданий 43 | { 44 | autors: String, # авторы 45 | compilers: String, # составители 46 | correct_level: Float, # уровень проверенности издания (0 - не проверено, 0.5 - проверено не полностью, 1 - проверено) 47 | cover_type: Int, # id типа обложки 48 | ebook: Boolean, # электронная книга или нет 49 | edition_id: Int, # id издания 50 | lang: String, # русскоязычное название языка 51 | lang_code: String, # код языка 52 | lang_id: Int, # id языка 53 | name: String, # название издания 54 | pic_num: Int, # ? 55 | plandate: ?|null, # ? 56 | plandate_txt: String, # пояснение насчет планируемой даты 57 | type: Int, # id типа издания 58 | year: Int # год издания 59 | }, 60 | ... 61 | ], 62 | id: Int, # id диктора 63 | image: String, # ссылка на основное фото 64 | image_preview: String, # ссылка на превью основного фото 65 | name: String, # имя 66 | name_rp: String, # имя в родительном падеже 67 | notes: String, # ? 68 | person_type: String, # тип персоны (в данном случае всегда dictor) 69 | sex: String, # пол (m - мужской, f - женский) 70 | site_links: [ |null # список официальных страниц 71 | { 72 | hint: String, # подсказка (например, соц. сеть) 73 | icon: String, # иконка (ссылка на изображение: https://fantlab.ru/img/{icon}) 74 | text: String, # название ссылки 75 | url: String # адрес ссылки 76 | }, 77 | ... 78 | ], 79 | stat: { # статистика 80 | editioncount: Int # количество изданий 81 | } 82 | } 83 | ``` 84 | -------------------------------------------------------------------------------- /Docs/edition.md: -------------------------------------------------------------------------------- 1 | # Издание 2 | 3 | ## Основная информация 4 | Запрос 5 | ``` 6 | GET /edition/{id} 7 | ``` 8 | Пример: 9 | > [/edition/1](https://api.fantlab.ru/edition/1) - Дэн Симменс "Гиперион" 10 | 11 | 12 | Ответ 13 | ``` 14 | edition_id: Int, # id издания 15 | edition_name: String, # название издания 16 | edition_type: String, # тип издания 17 | edition_type_plus: [ # доп. типы издания 18 | ...: String|null, 19 | ... 20 | ], 21 | edition_work_id: Int|null, # id произведения, где содержание такое же как в издании (журнал/сборник/антология) 22 | copies: Int, # тираж (0, если неизвестен) 23 | correct_level: Float, # степень проверенности издания (0 - не проверено, 0.5 - не полностью проверено, 1 - проверено) 24 | cover_type: String, # тип обложки 25 | creators: { 26 | authors: [ |null # список авторов 27 | { 28 | id: Int, # id автора 29 | is_opened: Boolean, # открыта ли страница автора 30 | name: String, # имя автора 31 | type: String # тип (autor - автор, art - художник) 32 | } 33 | ], 34 | compilers: [ |null # список составителей (если сборник/антология) 35 | { 36 | id: Int|null, # id составителя 37 | name: String, # имя составителя (может быть "не указан") 38 | type: String|null # тип (compiler) 39 | } 40 | ], 41 | publishers: [ |null # список издателей 42 | { 43 | id: Int|null, # id издателя 44 | name: String, # название издателя 45 | type: String|null # тип (publisher) 46 | } 47 | ] 48 | }, 49 | description: String, # описание 50 | format: String, # формат издания ("0", если неизвестен) 51 | format_mm: String?, # формат издания (в мм.) 52 | image: Url, # основная обложка издания 53 | image_preview: Url, # превью основной обложки 54 | isbns: [ # список ISBN 55 | ...: String|null, 56 | ... 57 | ], 58 | lang: String, # язык издания 59 | lang_code: String, # код языка издания 60 | notes: String, # примечания 61 | pages: Int, # количество страниц 62 | plan_date: String, # план выхода (дата текстом). если поле не пустое - значит издание еще не вышло 63 | plan_description: Srting, # примечание к плану выхода издания 64 | preread: Boolean, # есть ли отрывок для чтения 65 | series: [ # серии, в которые входит издание 66 | { |null 67 | id: Int, # id серии 68 | is_opened: Boolean, # открыта ли серия 69 | name: String, # название серии 70 | type: String # тип (series) 71 | } 72 | ], 73 | year: Int # год издания 74 | ``` 75 | 76 | 77 | ## Расширенная информация 78 | Запрос 79 | ``` 80 | GET /edition/{id}/extended 81 | ``` 82 | в расширенной информации о произведении добавляются поля: 83 | *content - содержание в виде массива строк (кол-во пробелов в начале строки - уровень вложения) 84 | images_plus - доп. изображения* 85 | 86 | Пример: 87 | > [/edition/1/extended](https://api.fantlab.ru/edition/1/extended) - Дэн Симменс "Гиперион" 88 | > [/edition/1?content=1&images_plus=1](https://api.fantlab.ru/edition/1?content=1&images_plus=1) - Альтернативный запрос с перечислением позиций 89 | 90 | 91 | Ответ 92 | ``` 93 | edition_id: Int, # id издания 94 | ... все поля обычной карточки издания (см. выше) и добаляются новые: ... 95 | 96 | content: [ |null # [content] содержание 97 | ...: String, 98 | ... 99 | ], 100 | images_plus: [ |null # [images_plus] доп.обложки и иллюстрации 101 | cover: [ # список обложек 102 | { 103 | image: Url, # обложка 104 | image_orig: Url, # обложка в большом разрешеним, если есть 105 | image_preview: Url, # превью обложки 106 | image_spine: Url, # корешок оложки, если он есть 107 | pic_text: String # описание или копирайт изображения 108 | } 109 | ], 110 | plus: [ |null # доп. изображения и иллюстрации 111 | { 112 | image: Url, # изображение 113 | image_preview: Url, # превью изображения 114 | pic_text: String # описание или копирайт изображения 115 | } 116 | ] 117 | ], 118 | ``` 119 | 120 | -------------------------------------------------------------------------------- /Docs/forum.md: -------------------------------------------------------------------------------- 1 | # Форум 2 | 3 | ## Плюсование/минусование поста 4 | В данном запросе потребуется обработать такие ситуации, как повторное плюсование/минусование, голосование за собственный пост etc. 5 | 6 | Запрос 7 | ``` 8 | /GET https://fantlab.ru/votepost{id}{plus|minus} 9 | ``` 10 | Параметры 11 | ``` 12 | id - id поста 13 | cookie - авторизационный хэдер (fl_s=*) 14 | ``` 15 | Пример 16 | ``` 17 | /GET https://fantlab.ru/votepost1plus - плюсануть пост #1 18 | ``` 19 | Ответ 20 | ``` 21 | HTML 22 | ``` 23 | -------------------------------------------------------------------------------- /Docs/marks.md: -------------------------------------------------------------------------------- 1 | 2 | # Оценки 3 | 4 | ## Оценки посетителя 5 | 6 | Запрос 7 | ``` 8 | GET /user/{id}/marks?page={page}&sort={mark|name|autor|date|year}&type={all|novel|story} 9 | ``` 10 | 11 | Параметры 12 | ``` 13 | id - id пользователя 14 | page - страница (необязательный; по-умолчанию 1). Запрос с пагинацией, отдает по 200 оценок на странице 15 | sort - вариант сортировки (необязательный; по-умолчанию mark) 16 | * mark - по оценке (высокие вначале) (default) 17 | * name - по названию произведения (по алфавиту) 18 | * autor- по автору произведения (по алфавиту) 19 | * date - по дате выставления оценки (новые - сверху) 20 | * year - по году выхода произведения (новые - сверху) 21 | type - фильтр по типам произведений 22 | * all - все (default) 23 | * novel- только романы 24 | * story- только повести, рассказы 25 | ``` 26 | 27 | Пример 28 | > [/user/1/marks?page=1&sort=date&type=novel](https://api.fantlab.ru/user/1/marks?page=1&sort=date&type=novel) - с 1 по 200 оценки (по убыванию даты выставления) creator'а, только романы 29 | 30 | Ответ: 31 | ``` 32 | { 33 | total_count: Int, # общее количество оценок с учетом фильтра типов (all|novel|story) - для пагинации 34 | items: [ # список оценок 35 | { 36 | mark_id: Int, # id оценки 37 | mark_date: DateTime, # дата-время выставления оценки ("2016-10-28 15:23:44") 38 | mark_date_iso: DateTime, # дата-время выставления оценки в формате ISO 8601 ("2016-10-28T15:23:44+03") 39 | mark: Int, # оценка произведению, данная вместе с отзывом (1-10) 40 | 41 | work_id: Int, # id произведения 42 | work_author: String, # автор(ы) произведения (на русском) 43 | work_author_orig: String, # автор(ы) произведения (на языке автора) 44 | work_name: String, # название произведения (на русском) 45 | work_name_orig: String, # название произведения (на языке написания) 46 | work_year: Int, # год публикации 47 | work_type: String, # тип произведения 48 | work_type_id: Int, # id типа произведения 49 | work_image: Url|null, # обложка/постер произведения 50 | 51 | user_id: Int, # id пользователя 52 | user_name: String, # login 53 | user_sex: Int, # пол: m - мужской, w - женский 54 | user_avatar: Url, # аватарка пользователя 55 | 56 | user_work_response_id: Int, # id отзыва юзера на это произведение (если отзыв написан) 57 | user_work_classif_flag: Boolean, # признак наличия классификации юзером на это произведение 58 | }, 59 | ... 60 | ], 61 | } 62 | ``` 63 | 64 | ## Расширенная информация 65 | ``` 66 | GET /user/{id}/marks/extended 67 | ``` 68 | в расширенной информации о произведении добавляются поля: 69 | *user_stat - статистика юзера о его оценках* 70 | 71 | Пример 72 | > [/user/1/marks/exdented](https://api.fantlab.ru/user/1/marks/extended) - вывод отзывов со статистикой 73 | 74 | Ответ: 75 | ``` 76 | { 77 | ... все поля обычных отзывов посетителя и добаляются новые: ... 78 | user_stat: # юзерская статистика по оценкам 79 | { 80 | marks_count: Int, # кол-во всего оценок (без учета фильтра) 81 | classif_count: Int, # кол-во классифицированных произведений 82 | marks_stats_marks: [ # кол-во оценок по баллам 83 | { 84 | mark: Int, # оценка (от 1 до 10) 85 | mark_count: Int, # количество данных оценок 86 | }, 87 | ... 88 | ], 89 | marks_stats_works: [ # кол-во оценок по типам произведений 90 | { 91 | work_type: String, # тип произведения 92 | work_type_id: Int, # id типа произведения 93 | mark_count: Int, # кол-во оценок этого типа произведений 94 | mark_avg: Float, # средний балл по ним 95 | }, 96 | ... 97 | ], 98 | }, 99 | } 100 | ``` 101 | 102 | 103 | ## Сокращенный вывод и фильтр по id 104 | ``` 105 | GET /user/{id}/marks?w={work_ids}&mini=1 106 | ``` 107 | для вывода оценок юзера на конкретные произведения предлагается исспользловать дополнительную фильтрацию по work_id: 108 | *work_ids - список запрашиваемых произведений (work_id через запятую) 109 | mini - режим мини-данных: выводятся только work_id, user_id, оценка* 110 | 111 | Пример 112 | > [/user/1/marks?w=1,92&mini=1](https://api.fantlab.ru/user/1/marks?w=1,92&mini=1) - вывод оценки для work_id 1 и 92 в режиме mini 113 | 114 | Ответ: 115 | ``` 116 | { 117 | total_count: Int, # общее количество (равно кол-во эллементов отдающихся в массиве items) 118 | items: [ # список оценок 119 | { 120 | mark: Int, # оценка произведению, данная вместе с отзывом (1-10) 121 | work_id: Int, # id произведения 122 | work_type_id: Int, # id типа произведения 123 | user_id: Int, # id пользователя 124 | user_work_response_id: Int, # id отзыва юзера (если он есть) 125 | user_work_classif_flag: Boolean, # проклассификацировано или нет юзером 126 | }, 127 | ... 128 | ], 129 | } 130 | ``` 131 | -------------------------------------------------------------------------------- /Docs/news.md: -------------------------------------------------------------------------------- 1 | # Новости 2 | 3 | API повторяет раздел https://fantlab.ru/news 4 | 5 | ## Список новостей 6 | Запрос 7 | ``` 8 | GET /news?page={page} 9 | ``` 10 | Параметры 11 | ``` 12 | page - страница (необязательный; по-умолчанию 1). Запрос с пагинацией, отдает по 10 новостей на странице 13 | mpp - позиций на странице (необязательный; по-умолчанию 10) 14 | ``` 15 | Сортировка по дате новости - от новых к старым датам. 16 | 17 | 18 | Пример 19 | > [/news](https://api.fantlab.ru/news) - 10 последних новостей сайта 20 | 21 | Ответ 22 | ``` 23 | { 24 | total_count: Int, # общее количество новостей 25 | items: [ # список новостей 26 | { 27 | type: String, # тип сегмента (в данном случае всегда news) 28 | id: Int, # id новости 29 | url: Url, # ссылка на страницу новости 30 | date: Date, # дата-время написания новости ("2019-02-26 03:00:00"), 31 | title: String, # заголовок новости 32 | image: Url, # картинка к новости, 33 | description: String, # текст новости (содержит a href-ссылки на сегменты библиобазы, другие bb- и html-тэги убраны) 34 | category: String, # категрия ности ("на сайте", "в мире ф&ф", "некролог" и пр.) 35 | author: String, # автор новости с ссылкой на юзера (пример: "Тиань") 36 | 37 | news_id: Int, # id новости (дубль id) 38 | news_date_iso, # дата-время новости в формате ISO 8601 ("2019-02-26T03:00:00+03") 39 | news_text, # необработанный текст новости 40 | short_text # краткий анонс новости 41 | }, 42 | ... 43 | ], 44 | } 45 | ``` 46 | 47 | -------------------------------------------------------------------------------- /Docs/oauth.md: -------------------------------------------------------------------------------- 1 | # OAuth-авторизация 2 | 3 | OAuth - протокол авторизации, в котором пользователь может разрешить приложению-клиенту доступ к данным пользователя (ресурсу) на основном сайте, не передавая приложению свои логин/пароль. 4 | 5 | Определения: 6 | - **Пользователь** - человек, зарегистрированный на сайте `fantlab.ru`. 7 | - **Клиент** - третья сторона (сервис/сайт/etc), которая может перенаправлять _пользователей_ на OAuth-авторизацию. 8 | - **Ресурс** - структурированная информация, которую может запрашивать _клиент_ на сайте `fantlab.ru` после авторизации с разрешения _пользователя_. 9 | 10 | ## Порядок авторизации 11 | 1. [Основной запрос на авторизацию](#Основной-запрос-на-авторизацию) 12 | 2. [Получение токена доступа](#Получение-токена-доступа) / [С использованием токена восстановления](#Получение-токена-доступа-с-использованием-токена-восстановления) 13 | 3. [Получение ресурса с использованием токена](#Получение-ресурса-с-использованием-токена) 14 | 15 | ## Основной запрос на авторизацию 16 | 17 | Запрос 18 | ``` 19 | GET /oauth/login?response_type=code&client_id={clien_id}&redirect_uri={redirect_uri}&redirect_noauth_uri={redirect_noauth_uri}&redirect_cancel_uri={redirect_cancel_uri} 20 | ``` 21 | 22 | Параметры 23 | ``` 24 | client_id - идентификатор клиента 25 | redirect_uri - uri для перенаправления после удачной авторизации 26 | redirect_noauth_uri - uri для перенаправления при неудачной авторизации (необязательный) 27 | redirect_cancel_uri - uri для перенаправления по нажатию кнопки "Отмена" (необязательный) 28 | ``` 29 | 30 | Пример 31 | ``` 32 | GET /oauth/login?response_type=code&client_id=1023&redirect_uri=http%3A%2F%2Fexample.com%2Fauth%2Fok 33 | ``` 34 | 35 | Ответ 36 | ``` 37 | уточнить 38 | ``` 39 | 40 | ## Получение токена доступа 41 | 42 | Запрос 43 | ``` 44 | GET /oauth/token?grant_type=authorization_code&code={code}&client_id={client_id}&client_secret={client_secret}&redirect_url=${redirect_url} 45 | ``` 46 | 47 | Параметры 48 | ``` 49 | code - код, полученный после авторизации 50 | client_id - идентификатор клиента 51 | client_secret - секрет клиента 52 | redirect_url - uri, используемый для перенаправления при логине 53 | ``` 54 | 55 | Пример 56 | ``` 57 | GET /oauth/token?grant_type=authorization_code&code=fhFPky2CG&client_id=1023&client_secret=mWoWHPDhg&redirect_url=http%3A%2F%2Fexample.com%2Fauth%2Foktoken 58 | ``` 59 | 60 | Ответ 61 | ``` 62 | { 63 | access_token: String, # токен доступа 64 | expires_in: Int, # время жизни токена (с.) 65 | refresh_token: String, # токен восстановления 66 | token_type: String # тип токена 67 | } 68 | ``` 69 | 70 | ## Получение токена доступа с использованием токена восстановления 71 | В случае, если при получении ресурса выдается ошибка `access_denied`, это означает, что истек срок действия токена. Получить новый токен можно с помощью токена восстановления (`refresh_token`), который был получен вместе с токеном доступа. 72 | 73 | Запрос 74 | ``` 75 | GET /oauth/token?grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&redirect_url={redirect_url} 76 | ``` 77 | 78 | Параметры 79 | ``` 80 | refresh_token - токен восстановления 81 | client_id - идентификатор клиента 82 | client_secret - секрет клиента 83 | redirect_url - uri, используемый для перенаправления при логине 84 | ``` 85 | 86 | Пример 87 | ``` 88 | GET /oauth/token?grant_type=refresh_token&refresh_token=fhFPky2CG&client_id=121212&client_secret=mWoWHPDhg&redirect_url=http%3A%2F%2Fexample.com%2Fcb%2F123 89 | ``` 90 | 91 | Ответ 92 | ``` 93 | { 94 | access_token: String, # новый токен доступа 95 | expires_in: Int, # время жизни токена (с.) 96 | refresh_token: String, # новый токен восстановления 97 | token_type: String # тип токена 98 | } 99 | ``` 100 | 101 | ## Получение ресурса с использованием токена 102 | 103 | Запрос 104 | ``` 105 | GET /oauth/get?oauth_token={oauth_token}&client_id={client_id}&resources={resources} 106 | ``` 107 | 108 | Параметры 109 | ``` 110 | oauth_token - токен доступа 111 | client_id - идентификатор клиента 112 | resources - список запрашиваемых ресурсов (в качестве разделителя используется `,`) 113 | ``` 114 | 115 | Пример 116 | ``` 117 | GET /oauth/get?oauth_token=mWoWHPDhg&client_id=121212&resources=em,rn,nk,sx,av,bd,cn,ct 118 | ``` 119 | 120 | Ответ 121 | ``` 122 | { 123 | id: Int|null, # [resources += id] id пользователя 124 | em: String|null, # [resources += em] адрес электронной почты 125 | sx: String|null, # [resources += sx] пол 126 | rn: String|null, # [resources += rn] настоящее имя 127 | nk: String|null, # [resources += nk] логин 128 | av: Url|null, # [resources += av] url аватарки 129 | bd: Long|null, # [resources += bd] дата рождения (UNIX-таймштамп) 130 | cn: String|null, # [resources += cn] страна 131 | ct: String|null # [resources += ct] город 132 | } 133 | ``` 134 | 135 | ## Порядок получения `code` для клиента 136 | Для тестирования можно использовать следующие параметры (ограничены по количеству обращений): 137 | ``` 138 | code = test321 139 | client_secret = 2onNZkfjEK 140 | ``` 141 | При запуске приложения в релиз обратитесь на `support@fantlab.ru` для получения собственного кода для клиента. 142 | -------------------------------------------------------------------------------- /Docs/other.md: -------------------------------------------------------------------------------- 1 | ## Теги, ссылки и пр. 2 | В редакторе хватает кастомных тегов: 3 | ``` 4 | [b]text[/b] - жирный текст 5 | [i]text[/i] - курсив 6 | [u]text[/u] - подчеркнутый текст 7 | [s]text[/s] - зачеркнутый текст 8 | 9 | [p]text[/p] - абзац 10 | [q]text[/q] - цитата 11 | [h]text[/h] - спойлер 12 | 13 | [LIST] 14 | [*]1st 15 | [*]2nd 16 | [*]3rd 17 | ... 18 | [/LIST] - список 19 | 20 | [IMG]image_link[/IMG] - ссылка на изображение 21 | [VIDEO=youtube_link] - ссылка на видео на Youtube 22 | ``` 23 | 24 | В приходящем с сервера тексте могут быть ссылки на внутренние сущности базы: 25 | ``` 26 | [autor=1]...[/autor] = "/autor1" 27 | [work=1]...[/work] = "/work1" 28 | [edition=1]...[/edition] = "/edition1" 29 | 30 | [person=1]...[/person] = "/person1" 31 | [user=1]...[/user] = "/user1" 32 | [art=1]...[/art] = "/art1" 33 | [dictor=1]...[/dictor] = "/dictor1" 34 | [series=1]...[/series] = "/series1" 35 | [film=1]...[/film] = "/film1" 36 | [translator=1]...[/translator] = "/translator1" 37 | [pub=1]...[/pub] = "/publisher1" 38 | 39 | [link=blogarticle1]...[/link] = "/blogarticle1" 40 | [url=http://google.com]...[/url] = "http://google.com" - внешняя ссылка 41 | ``` 42 | 43 | Также есть смайлы (набор `Kolobok smiles`), они в редакторе задаются через `:name:`. 44 | -------------------------------------------------------------------------------- /Docs/private-messages.md: -------------------------------------------------------------------------------- 1 | # Личка 2 | 3 | ## Отправка/сохранение в черновик сообщения 4 | Запрос 5 | ``` 6 | /POST(Multipart) https://fantlab.ru/user{id}/sendprivatemessage 7 | ``` 8 | Параметры 9 | ``` 10 | id - id пользователя, которому отправляется сообщение 11 | cookie - авторизационный хэдер (fl_s=*) 12 | 13 | message - текст сообщения 14 | file1 (с полем fileName и типом application/octet-stream), file2... - приложенные файлы 15 | mode - режим отправки, реальная (send) или сохранение в черновик (preview) 16 | action - действие (/user{id}/sendprivatemessage) 17 | ``` 18 | Пример 19 | ``` 20 | /POST(Multipart) https://fantlab.ru/user1/sendprivatemessage (message=Привет!) - отправить сообщение "Привет!" creator'у 21 | ``` 22 | Ответ 23 | ``` 24 | HTML-страница пользователя, которому отправляли сообщение 25 | ``` 26 | 27 | ## Подтверждение отправки черновика 28 | Запрос 29 | ``` 30 | /GET https://fantlab.ru/user{id}/submitpmpreview 31 | ``` 32 | Параметры 33 | ``` 34 | id - id пользователя, которому писали сообщение 35 | cookie - авторизационный хэдер (fl_s=*) 36 | ``` 37 | Пример 38 | ``` 39 | /GET https://fantlab.ru/user1/submitpmpreview - подтвердить отправку сообщения creator'у 40 | ``` 41 | Ответ 42 | ``` 43 | HTML-страница пользователя, которому писали сообщение 44 | ``` 45 | 46 | ## Отмена отправки черновика 47 | Запрос 48 | ``` 49 | /GET https://fantlab.ru/user{id}/cancelpmpreview 50 | ``` 51 | Параметры 52 | ``` 53 | id - id пользователя, которому писали сообщение 54 | cookie - авторизационный хэдер (fl_s=*) 55 | ``` 56 | Пример 57 | ``` 58 | /GET https://fantlab.ru/user1/cancelpmpreview - отменить отправку сообщения creator'у 59 | ``` 60 | Ответ 61 | ``` 62 | HTML-страница пользователя, которому писали сообщение 63 | ``` 64 | -------------------------------------------------------------------------------- /Docs/publisher.md: -------------------------------------------------------------------------------- 1 | # Издательства 2 | 3 | ## Список издательств 4 | 5 | Запрос 6 | ``` 7 | GET /publishers?letter={letter}&country_id={country_id}&type={type}&from={from}&to={to}&sort={sort}&page={page} 8 | ``` 9 | 10 | Параметры 11 | ``` 12 | letter - первая буква названия, от А до Я, от A до Z (необязательный; по умолчанию любая [пустая строка]) 13 | country_id - id страны (необязательный; по умолчанию все [0]) 14 | type - категория издательств (необязательный; по умолчанию все [0]) 15 | * 0 - все 16 | * 1 - фантастические 17 | * 2 - аудио-издательства 18 | * 3 - электронные 19 | * 4 - современные 20 | * 5 - советские 21 | * 6 - дореволюционные 22 | * 7 - эмигрантские 23 | * 8 - русское зарубежье 24 | from - с какого года (необязательный; по умолчанию за все года [пустая строка]) 25 | to - по какой год (необязательный; по умолчанию за все года [пустая строка]) 26 | sort - вариант сортировки (необязательный; по умолчанию по названию [name]) 27 | * name - по названию 28 | * editions_count - по количеству изданий 29 | * country - по стране 30 | * city - по городу 31 | page - номер страницы (необязательный; по умолчанию 1). Запрос с пагинацией, отдает по 250 результатов на странице 32 | ``` 33 | 34 | Пример 35 | > [/publishers?country_id=2&sort=editions_count](https://api.fantlab.ru/publishers?country_id=2&sort=editions_count) - издательства США, отсортированные по количеству изданий 36 | 37 | Ответ: 38 | ``` 39 | [ 40 | { 41 | alt_names: String, # альтернативные названия 42 | audiopub: Boolean, # аудио-издательство 43 | city: String, # город 44 | closed: Boolean, # издательство закрыто 45 | country_id: Int, # id страны (флаг, если country_id != 0, всегда располагается по ссылке https://data.fantlab.ru/images/flags/{country_id}.png) 46 | country_name: String|null, # страна (null, когда country_id = 0) 47 | editions_count: Int, # количество изданий 48 | epub: Boolean, # электронное издательство 49 | is_fant: Boolean|null, # фантастическое издательство 50 | name: String, # название 51 | nopub: Boolean, # не является издательством как таковым 52 | publisher_id: Int, # id (логотип, если есть, всегда располагается по ссылке htpps://data.fantlab.ru/images/publisher/{publisher_id}_1) 53 | site: Url|null, # ссылка на сайт 54 | year_close: Int|null, # год закрытия (null или 0, когда closed = 0) 55 | year_open: Int|null # год открытия 56 | }, 57 | ... 58 | ] 59 | ``` 60 | 61 | ## Топ-30 издательств 62 | 63 | Запрос 64 | ``` 65 | GET /publishers/top.json?country_id={country_id} 66 | ``` 67 | 68 | Параметры 69 | ``` 70 | country_id - id страны (необязательный; по умолчанию все [0]) 71 | ``` 72 | 73 | Пример 74 | > [/publishers/top.json?country_id=1](https://api.fantlab.ru/publishers/top.json?country_id=1) - топ-30 издательств России 75 | 76 | Ответ: 77 | ``` 78 | аналогичен ответу /publishers 79 | ``` 80 | -------------------------------------------------------------------------------- /Docs/pubnews.md: -------------------------------------------------------------------------------- 1 | # Новинки и планы издательств, авторов 2 | 3 | API повторяет раздел https://fantlab.ru/pubnews 4 | Веб-версия строится ровно по тем же данным, что и выводятся в АПИ. 5 | 6 | В разделе АПИ три подраздела: Новинки издательств, Планы издательств, Планы авторов. 7 | Первые два - списки изданий. Третьей - список произведений. 8 | 9 | **Запрос** 10 | ``` 11 | GET /pubnews - Новинки издательств 12 | GET /pubplans - Планы издательств 13 | GET /autplans - Планы авторов 14 | ``` 15 | 16 | **Параметры** 17 | 18 | В урле запроса допустимы параметры: lang, sort, page, pub_id. 19 | 20 | lang - язык. 21 | ``` 22 | lang=0 - русскоязычное 23 | lang=1 - зарубежное 24 | lang=2 - и то, и другое 25 | ``` 26 | 27 | sort - сортировка. В каждом из трёх подразделов свой набор доступных сортировок: 28 | ``` 29 | /pubnews.json 30 | date - по дате (выхода) 31 | popularity - по популярности (*) 32 | type - по типу (издания) 33 | pub - по издательству и серии 34 | author - по автору 35 | title - по наименованию 36 | /pubplans.json - Планы издательств 37 | corect - по изменению (дате последней правки издания) - единственное отличие от набора сортировок /pubnews.json 38 | popularity - по популярности (*) 39 | date - по дате (выхода) 40 | type - по типу (издания) 41 | pub - по издательству и серии 42 | author - по автору 43 | title - по наименованию 44 | /autplans.json - Планы авторов 45 | corect - по изменению (дате добавления произведения) 46 | popularity - по популярности (*) 47 | author - по автору 48 | title - по наименованию 49 | ``` 50 | `(*)` на данный момент считается на основе количества добавлений на книжные полки и количества подписок на выход книги, если она в планах 51 | 52 | pub_id - выбор конкретного издательства по его ID. 53 | Доступно только в разделах pubnews и pubplans. 54 | 55 | page - страница. 56 | 57 | **Пример** 58 | > [/pubnews](https://api.fantlab.ru/pubnews) - Новинки издательств 59 | > [/pubplans](https://api.fantlab.ru/pubplans) - Планы издательств 60 | > [/autplans](https://api.fantlab.ru/autplans) - Планы авторов 61 | 62 | 63 | 64 | **Ответ** 65 | 66 | all_pages_access_to_user_class - номер класса посетителя, начиная с которого (включительно) можно открывать ему page=all. 67 | Это небольшая защита от излишней нагрузки на сервер, а также от пауков-парсеров, которым удобнее одну страницу парсить. 68 | 69 | image_url - префикс урла всех картинок (ворки и эдишны) 70 | 71 | interval_days - за сколько дней показываются новинки и планы (это можно где-то снизу под звёздочкой указать, как на сайте) 72 | 73 | lang - выбранный язык (0 - русский, 1 - зарубежный, 2 - оба) 74 | 75 | mode - это своего рода урл после fantlab.ru, но без параметров. Значения: pubnews, pubplans, autplans. 76 | 77 | objects - собственно массив-список объектов (изданий или произведений). 78 | В нём: 79 | - approx_release_date - ожидаемая дата релиза издания. Используется только на бэке. На фронте - нет. 80 | - approx_release_date_iso - ожидаемая дата релиза издания в ISO 8601 81 | - correct_date - дата последней правки издания/ворка 82 | - correct_date_iso - дата последней правки издания/ворка в ISO 8601 83 | - date - дата или выхода или плана выхода издания. На сайте справа от издания выводится именно она 84 | - first_edition - является ли первым изданием 85 | - ozon_available - доступность на озоне (0,1) 86 | - ozon_cost - цена на озоне 87 | - ozon_id - id на озоне 88 | - аналогично с лабиринтом 89 | - plan_date и plandate - дата выхода. В разных форматах. Но выводить нужно всё равно просто date. 90 | - plan_description - описание/примечание к плану издания книги 91 | - popularity - рейтинг популярности 92 | - popularity_date_of_calc - дата/время последнего пересчета рейтинга популярности 93 | - popularity_date_of_calc_iso - дата/время последнего пересчета рейтинга популярности в ISO 8601 94 | - preread - есть ли кусок pdf-а для ознакомления (0, 1) 95 | - release_date - Фактическое начало продаж 96 | - sort_string - по этому полю идёт сортировка при sort in (author, title). С этого поля можно откусывать первый символ, чтобы рисовать подзаголовки: "авторы на букву А, затем Б...". Как на сайте. 97 | - the_only_work - вложенный хэш, которые заполняется данными о произведении, если оно в этом издании одно 98 | - ...остальное должно быть понятно и так 99 | 100 | objects_in_page - сколько объектов на странице показывается 101 | 102 | pub_id и pub_name - издательство, выбранное из ниспадающего списка (для разделов новинок и планов издательств) 103 | 104 | publisher_list - список всех издательств, чьи издания встречены в этом разделе. Для выбора из ниспадающего списка. 105 | 106 | pubnews_communities - доп.информация об рубриках в блогах, де публикуются новинки. 107 | -------------------------------------------------------------------------------- /Docs/recommendations.md: -------------------------------------------------------------------------------- 1 | # Рекомендации 2 | 3 | ## Удаление рекомендации в мусорку 4 | Запрос 5 | ``` 6 | /GET https://fantlab.ru/rtrashwork{id} 7 | ``` 8 | Параметры 9 | ``` 10 | id - id произведения 11 | cookie - авторизационный хэдер (fl_s=*) 12 | ``` 13 | Пример 14 | ``` 15 | /GET https://fantlab.ru/rtrashwork1 - удаление "Гипериона" в мусорку рекомендаций 16 | ``` 17 | Ответ 18 | ``` 19 | HTML-шаблон 20 | ``` 21 | 22 | ## Правка мусорки рекомендаций 23 | Запрос 24 | ``` 25 | /POST https://fantlab.ru/rectrash/saverecomstrash 26 | ``` 27 | Параметры 28 | ``` 29 | cookie - авторизационный хэдер (fl_s=*) 30 | 31 | w{id_1} = on (достать из мусорки) 32 | w{id_2} = off (оставить в мусорке) 33 | action = rectrash/saverecomstrash 34 | ``` 35 | Ответ 36 | ``` 37 | HTML-шаблон 38 | ``` 39 | -------------------------------------------------------------------------------- /Docs/responses.md: -------------------------------------------------------------------------------- 1 | 2 | # Отзывы 3 | 4 | ## Отзывы на все произведения автора 5 | 6 | Запрос 7 | ``` 8 | GET /autor/{id}/responses?page={page}&sort={date|rating|mark} 9 | ``` 10 | 11 | Параметры 12 | ``` 13 | id - id автора 14 | page - страница (необязательный; по-умолчанию 1). Запрос с пагинацией, отдает по 50 отзывов на странице 15 | sort - вариант сортировки (необязательный; по-умолчанию по date - т.е. вначале самые новые отзывы) 16 | * date - по дате (default) 17 | * rating - по рейтингу отзыва 18 | * mark - по оценке 19 | ``` 20 | 21 | Пример 22 | > [/autor/133/responses?page=2&sort=rating](https://api.fantlab.ru/autor/133/responses?sort=rating) - 50 хороших отзывы на произведения Дж. Р.Р. Мартина 23 | 24 | Ответ: 25 | ``` 26 | { 27 | total_count: Int, # общее количество отзывов 28 | items: [ // список отзывов 29 | { 30 | response_id: Int, # id отзыва 31 | response_date: DateTime, # дата-время написания отзыва ("2016-10-28 15:23:44") 32 | response_date_iso: DateTime, # дата-время написания отзыва в формате ISO 8601 ("2016-10-28T15:23:44+03") 33 | response_text: String, # текст отзыва 34 | response_votes: int, # рейтинг отзыва 35 | mark: Int, # оценка произведению, данная вместе с отзывом (1-10) 36 | 37 | work_id: Int, # id произведения 38 | work_author: String, # автор(ы) произведнния (на русском) 39 | work_author_orig: String, # автор(ы) произведнния (на языке автора) 40 | work_name: String, # название произведения (на русском) 41 | work_name_orig: String, # название произведения (на языке написания) 42 | work_year, # год публикации произведения 43 | work_type: String, # тип произведения 44 | work_type_id: Int, # id типа произведения 45 | work_image: Url, # обложка/постер произведения 46 | 47 | user_id: Int, # юзер-id 48 | user_name: String, # login 49 | user_sex: Int, # мол: m- мужской, w-женский 50 | user_avatar: Url, # аватарка юзера 51 | }, 52 | ... 53 | ] 54 | } 55 | ``` 56 | 57 | 58 | ## Отзывы на одно произведение 59 | 60 | ``` 61 | GET /work/{id}/responses?page={page}&sort={date|rating|mark} 62 | ``` 63 | 64 | Параметры 65 | ``` 66 | id - id автора 67 | page - страница (необязательный; по-умолчанию 1). Запрос с пагинацией, отдает по 15 отзывов на странице 68 | sort - вариант сортировки (необязательный; по-умолчанию по rating - т.е. вначале самые хорошие отзывы (в отличие от списка отзывов на автора - там по умолчанию "новые") 69 | * date - по дате 70 | * rating - по рейтингу отзыва (default) 71 | * mark - по оценке 72 | ``` 73 | 74 | Пример: 75 | > [/work/1/responses](https://api.fantlab.ru/work/1/responses) - хорошие отызывы на "Гиперион" Дэна Симменса 76 | > [/work/1/responses?sort=date](https://api.fantlab.ru/work/1/responses?sort=date) - новые отзывы на "Гиперион" Дэна Симменса 77 | 78 | Ответ: 79 | ``` 80 | полностью соответвует выдачи как у списка отзывов автора (см. выше) 81 | ``` 82 | 83 | 84 | ## Отзывы посетителя 85 | 86 | Запрос 87 | ``` 88 | GET /user/{id}/responses?page={page}&sort={date|rating|mark} 89 | ``` 90 | 91 | Параметры 92 | ``` 93 | id - id пользователя 94 | page - страница (необязательный; по-умолчанию 1). Запрос с пагинацией, отдает по 50 отзывов на странице 95 | sort - вариант сортировки (необязательный; по-умолчанию date) 96 | * date - по дате (default) 97 | * rating - по рейтингу 98 | * mark - по оценке 99 | ``` 100 | 101 | Пример 102 | > [/user/1/responses?page=2&sort=rating](https://api.fantlab.ru/user/1/responses?page=2&sort=rating) - 50-100 отзывы (по убыванию рейтинга) creator'а 103 | 104 | Ответ 105 | ``` 106 | полностью соответвует выдачи как у списка отзывов автора (см. выше) 107 | ``` 108 | 109 | 110 | ## Новые отзывы на сайте 111 | Запрос 112 | ``` 113 | GET /responses?page={page} 114 | ``` 115 | 116 | Параметры 117 | ``` 118 | page - страница (необязательный; по-умолчанию 1). Запрос с пагинацией, отдает по 50 отзывов на странице. максимум 20 страниц. 119 | ``` 120 | 121 | Пример 122 | > [/responses](https://api.fantlab.ru/responses) - 50 самых новых отзывов на сайте 123 | 124 | Ответ 125 | ``` 126 | полностью соответвует выдаче как у списка отзывов автора (см. выше) 127 | ``` 128 | 129 | ## Плюсование/минусование отзыва 130 | В данном запросе необходимо обрабатывать такие ситуации, как повторное плюсование/минусование, голосование за собственный отзыв, запрет на минусование отзыв для "минусаторов", запрет на минусование пользователям, не набравшим 300 баллов за собственные отзывы etc. 131 | 132 | Запрос 133 | ``` 134 | GET https://fantlab.ru/vote{response_id}{plus|minus} 135 | ``` 136 | Параметры 137 | ``` 138 | response_id - id отзыва 139 | cookie - авторизационный хэдер (fl_s=*) 140 | ``` 141 | Пример 142 | ``` 143 | GET https://fantlab.ru/vote1plus - плюсануть отзыв #1 144 | ``` 145 | Ответ 146 | ``` 147 | r{response_id}={new_vote_count} 148 | ``` 149 | -------------------------------------------------------------------------------- /Docs/search-blogs.md: -------------------------------------------------------------------------------- 1 | # Поиск по блогам 2 | 3 | Общие замечания по выдаче: 4 | 1. Блоги в данном контексте - синоним авторских колонок (АК). Сюда же включены и рубрики, куда могут публиковаться статьи из разных АК (впрочем, могут быть и статьи, размещенные исключительно в рубриках). 5 | 2. Запрос поддерживает пагинацию. На одной странице в поиске по названиям статей выдается по 30 результатов, в поиске по содержанию статей - по 10 результатов. Максимально возможное общее количество результатов равно 1000. 6 | 3. В ответе сервера есть поле *attrs*, содержащее список полей в выдаче *matches*. Каждое поле обозначено именем и целочисленным типом. Например, "1" - Int, "7" - String. 7 | 4. Запрос поиска по содержанию статей *очень* тяжелый, поскольку в ответ приходят полные тексты. Даже несмотря на ограничение в 10 статей на страницу, размер ответа может достигать нескольких мегабайт, будьте внимательны. 8 | ## Общая структура ответа 9 | ``` 10 | { 11 | attrs: { # список полей в выдаче 12 | {attr}: Int, 13 | ... 14 | }, 15 | error: String, # текст ошибки, если есть 16 | fields: [ # список полей, по которым осуществляется поиск 17 | ...: String, 18 | ... 19 | ], 20 | matches: [ # список найденных результатов 21 | { 22 | ... 23 | }, 24 | ... 25 | ], 26 | time: Float, # длительность поиска в секундах 27 | total: Int, # общее количество результатов 28 | total_found: Int, # общее количество найденных результатов (но получить можно максимум total) 29 | type: String, # категория поиска 30 | warning: String, # предупреждение, если есть 31 | words: { 32 | {word}: { 33 | docs: Int, # количество найденных совпадений по данному слову 34 | hits: Int # количество найденных уникальных совпадений по данному слову 35 | }, 36 | ... 37 | } 38 | } 39 | ``` 40 | 41 | 42 | ## Поиск по блогам 43 | 44 | Запрос 45 | ``` 46 | GET /search-blog.json?q={query}&blogs={blogs}&t={type}&alg={algorithm}&period={period}&sortby={sort}&page={page}&onlymatches={0|1} 47 | ``` 48 | 49 | Параметры 50 | ``` 51 | query - строка поиска. В качестве разделителя используется "+" 52 | blogs - в каких блогах/рубриках искать (необязательный; по-умолчанию во всех). Несколько блогов/рубрик передаются отдельными параметрами: чтобы искать одновременно в рубриках "Издательство «Эксмо»" и "Издательство «Азбука»", надо передать в запросе их id: ...&blogs=971&blogs=976&... Если нужен поиск только по блогам (то есть за исключением рубрик), надо передать ...&blogs=a&... Смешивать эти варианты не рекомендуется 53 | type - где искать (необязательный; по-умолчанию t) 54 | * t - только в названиях статей 55 | * m - по содержанию статьи 56 | algorithm - как искать (необязательный; по-умолчанию 0) 57 | * 0 - поиск по словам запроса 58 | * 1 - поиск фразы целиком (как есть) 59 | period - за какой период (необязательный; по-умолчанию 0) 60 | * 0 - за все время 61 | * любое N > 0 - за последние N суток (предусмотренные значения - 1, 7, 31, 180, 365) 62 | sort - сортировка (необязательный; по-умолчанию rel) 63 | * rel - по релевантности 64 | * dat - по актуальности 65 | page - номер страницы (необязательный; по-умолчанию 1) 66 | onlymatches - выдавать только содержимое массива matches (необязательный; по-умолчанию 0) 67 | ``` 68 | 69 | Пример 70 | > [/search-blog.json?q=фантастика&t=t&onlymatches=1](https://api.fantlab.ru/search-blog.json?q=фантастика&t=t&onlymatches=1) - поиск статей со словом "фантастика" в названии по всем блогам за все время 71 | 72 | Ответ (при запросе с параметром **onlymatches=1**) 73 | ``` 74 | [ 75 | { 76 | blog_ids: [ # список id блогов/рубрик, в которых размещена данная статья 77 | ...: Int, 78 | ... 79 | ], 80 | blog_is_community: [ # список того, являются вышеуказанные блоги рубриками (на практике совершенно бесполезное поле, если блогов больше одного) 81 | ...: Boolean, 82 | ... 83 | ], 84 | date_of_add: Long, # дата создания статьи (UNIX-таймштамп) 85 | doc: Int, # ? 86 | is_opened: Boolean, # статья опубликована (не черновик) 87 | likes_count: Int, # количество лайков (aka "Спасибо") 88 | message_text: String|null, # текст статьи (поле есть, только если это поиск по содержанию статей) 89 | tags: String, # теги 90 | topic_id: Int, # id статьи 91 | topic_name: String, # название статьи 92 | topic_rating: [ 93 | ...: Float # рейтинг статьи (нелинейно зависит от количества лайков, количества подписчиков, количества комментариев и того, как давно статья была опубликована; чаще всего 0) 94 | ], 95 | views: Int, # количество просмотров (значение некорректно, не стоит его принимать во внимание) 96 | weight: Int # степень релевантности (влияет на порядковый номер в выдаче - чем больше, тем выше) 97 | }, 98 | ... 99 | ] 100 | ``` 101 | -------------------------------------------------------------------------------- /Docs/search-forum.md: -------------------------------------------------------------------------------- 1 | # Поиск по форуму 2 | 3 | Общие замечания по выдаче: 4 | 1. Запрос поддерживает пагинацию. На одной странице выдается по 30 результатов, максимально возможное общее количество результатов равно 1000. 5 | 2. Результаты фильтруются с учетом того, к каким форумам у пользователя есть доступ. 6 | 3. В ответе сервера есть поле *attrs*, содержащее список полей в выдаче *matches*. Каждое поле обозначено именем и целочисленным типом. Например, "1" - Int, "7" - String. 7 | ## Общая структура ответа 8 | ``` 9 | { 10 | attrs: { # список полей в выдаче 11 | {attr}: Int, 12 | ... 13 | }, 14 | error: String, # текст ошибки, если есть 15 | fields: [ # список полей, по которым осуществляется поиск 16 | ...: String, 17 | ... 18 | ], 19 | matches: [ # список найденных результатов 20 | { 21 | ... 22 | }, 23 | ... 24 | ], 25 | time: Float, # длительность поиска в секундах 26 | total: Int, # общее количество результатов 27 | total_found: Int, # общее количество найденных результатов (но получить можно максимум total) 28 | type: String, # категория поиска 29 | warning: String, # предупреждение, если есть 30 | words: { 31 | {word}: { 32 | docs: Int, # количество найденных совпадений по данному слову 33 | hits: Int # количество найденных уникальных совпадений по данному слову 34 | }, 35 | ... 36 | } 37 | } 38 | ``` 39 | 40 | 41 | ## Поиск по форуму 42 | 43 | Запрос 44 | ``` 45 | GET /search-forum.json?q={query}&forums={forums}&topics={topics}&t={type}&alg={algorithm}&period={period}&sortby={sort}&page={page}&onlymatches={0|1} 46 | ``` 47 | 48 | Параметры 49 | ``` 50 | query - строка поиска. В качестве разделителя используется "+" 51 | forums - в каких форумах искать (необязательный; по-умолчанию во всех). Несколько форумов передаются отдельными параметрами: чтобы искать одновременно в форумах "Кино" и "Музыка", надо передать в запросе их id: ...&forums=5&forums=8&... 52 | topics - в каких темах искать (необязательный; по-умолчанию во всех). Схема та же, что и для forums 53 | type - где искать (необязательный; по-умолчанию t) 54 | * t - только в названиях тем 55 | * m - в сообщениях 56 | algorithm - как искать (необязательный; по-умолчанию 0) 57 | * 0 - поиск по словам запроса 58 | * 1 - поиск фразы целиком (как есть) 59 | period - за какой период (необязательный; по-умолчанию 0) 60 | * 0 - за все время 61 | * любое N > 0 - за последние N суток (предусмотренные значения - 1, 7, 31, 180, 365) 62 | sort - сортировка (необязательный; по-умолчанию rel) 63 | * rel - по релевантности 64 | * dat - по актуальности 65 | page - номер страницы (необязательный; по-умолчанию 1) 66 | onlymatches - выдавать только содержимое массива matches (необязательный; по-умолчанию 0) 67 | ``` 68 | 69 | Пример 70 | > [/search-forum.json?q=фантастика&forums=14&t=t&onlymatches=1](https://api.fantlab.ru/search-forum.json?q=фантастика&forums=14&t=t&onlymatches=1) - поиск тем со словом "фантастика" в названии в форуме "Произведения, авторы, жанры" за все время 71 | 72 | Ответ (при запросе с параметром **onlymatches=1**) 73 | ``` 74 | [ 75 | { 76 | add_time: Long, # дата создания темы (UNIX-таймштамп) 77 | doc: Int, # ? 78 | forum_id: Int, # id форума 79 | forum_name: String, # название форума 80 | is_closed: Boolean, # тема закрыта 81 | is_pinned: Boolean, # тема закреплена 82 | message_count: Int, # количество сообщений 83 | name: String, # название темы 84 | topic_id: Int, # id темы 85 | user_id: Int, # id топикстартера 86 | user_name: String, # логин топикстартера 87 | view_count: Int, # количество просмотров 88 | weight: Int # степень релевантности (влияет на порядковый номер в выдаче - чем больше, тем выше) 89 | }, 90 | ... 91 | ] 92 | ``` 93 | 94 | Пример 95 | > [/search-forum.json?q=фантастика&t=m&onlymatches=1](https://api.fantlab.ru/search-forum.json?q=фантастика&t=m&onlymatches=1) - поиск сообщений со словом "фантастика" в тексте по всем форумам за все время 96 | 97 | Ответ (при запросе с параметром **onlymatches=1**) 98 | ``` 99 | [ 100 | { 101 | date_of_add: Long, # дата отправки сообщения (UNIX-таймштамп) 102 | doc: Int, # ? 103 | forum_id: Int, # id форума 104 | forum_name: String, # название форума 105 | is_censored: Boolean, # сообщение зацензурено 106 | message_id: Int, # id сообщения 107 | message_text: String, # текст сообщения 108 | topic_closed: Boolean, # тема закрыта 109 | topic_id: Int, # id темы 110 | topic_message_count: Int, # количество сообщений в теме 111 | topic_message_index: Int, # номер сообщения в теме 112 | topic_name: String, # название темы 113 | topic_pinned: Boolean, # тема закреплена 114 | user_id: Int, # id автора сообщения 115 | user_name: String, # логин автора сообщения 116 | weight: Int # степень релевантности (влияет на порядковый номер в выдаче - чем больше, тем выше) 117 | }, 118 | ... 119 | ] 120 | ``` 121 | -------------------------------------------------------------------------------- /Docs/search-ids.md: -------------------------------------------------------------------------------- 1 | ## Миникарточки элементов базы 2 | 3 | Основная краткая выдача информации по базе в виде лид-карточек. Разбита по блоки соответвующие сегментам базы: авторы/произведения/издания. Отдается с учетом релевантности найденнему по запросу. 4 | Структура ответа - сокращенный вариант отдельных позиций библиобазы. Исспользуется в выдачи листингов/подборок (в первую очередь - в поиске). 5 | 6 | Основные поля миникарточки (есть у всех сегментов): 7 | ``` 8 | type: String, # сегмент (сущность/раздел) базы: work, edition, author/autor, art и пр. 9 | # полный список сегментов см. в общем README) 10 | id: Int, # id позиции данного сегмента (вместе с type дают уникальный fantlab-id: {type}{id} 11 | # примеры: work101, edition14215, author12 и т.д. 12 | 13 | title: String, # заголовок (часто составное как "автор «название»") 14 | description: String, # описание (краткое, не более 500 символов) 15 | image: Url, # титульная картинка 16 | image_preview: Url, # ссылка на превью-картинка (50х70 px) 17 | url: Url, # ссылка на страницу в фл-базе 18 | 19 | name: String, # имя персоны (название) 20 | name_orig: String, # имя или название в оргинале (это поле есть не всегда) 21 | is_opened: Boolean, # карточка открыта для просмотра (это поле есть не всегда, обычно есть только у авторов/персон) 22 | ``` 23 | 24 | 25 | 26 | Полный формат отдачи миникарточек: 27 | ``` 28 | { 29 | authors: [ 30 | { 31 | type: String, # сущность/раздел базы (autor) 32 | id: Int, # id позиции данного раздела (в данном случае - ID автора) 33 | name: String, # имя 34 | name_orig: String, # имя в оригинале 35 | title: String, # имя рус и оргинальное: "Джон Смит (Jonh Smith)" 36 | description: String, # краткое описание (не более 500 символов) 37 | image: Url, # ссылка на фото автора 38 | image_preview: Url, # ссылка на превью 50х70 39 | url: Url, # ссылка на страницу автора в ФЛ-базе 40 | 41 | birthday: Data, # дата или год рождения 42 | sex: String, # пол (m/w) 43 | is_opened: Boolean, # открыта ли страница автора 44 | }, 45 | ... 46 | ], 47 | 48 | works: [ 49 | { 50 | type: String, # сущность/раздел базы (work) 51 | id: Int, # id произведения 52 | name: String, # имя 53 | name_orig: String, # имя в оригинале 54 | title: # заглавие: авторы и название произведения в одну строку 55 | description: String, # краткая аннотация произведения (не более 500 символов) 56 | image: Url, # ссылка на обложку-постер для произведения 57 | image_preview: Url, # ссылка на его превью 58 | url: Url, # ссылка на страницу произведения в ФЛ-базе 59 | 60 | year: Year, # год публикации 61 | published: Boolean, # опубликовано или нет (1 - опубликовано / 0 - запланировано к выходу) 62 | 63 | name_type: String, # тип произведения на русском 64 | name_type_id: Int, # id типа произведения 65 | name_type_icon: String, # тип произведения как тип (novel, cycle и пр.) 66 | name_type_image: Url, # ссылка на иконку-заглушку для постера. для использования если нет самого постера 67 | 68 | creators: { # массив авторов проивезедений. 69 | authors: [ # авторы произвдений 70 | { 71 | type: String, # сущность. могут быть autor или art (для графических) 72 | id: Int, # id автора 73 | name: String, # имя автора 74 | is_opened: Boolean, # открыт ли автор 75 | }, 76 | ... 77 | ], 78 | 79 | saga: { # цикл, краткая информация о родительском цикле 80 | type: String, # сущность/раздел базы (work) 81 | id: Int, # work_id 82 | name: String, # название цикла 83 | name_type: String, # тип (цикл, роман-эпопея, межавторский цикл и пр.) 84 | }, 85 | 86 | stat: { # рейтинг и статистика произведения 87 | rating: Float, # рейтинг (пример: "8.79") 88 | voters: Int, # кол-во оценок 89 | responses: Int, # кол-во отзывов 90 | }, 91 | }, 92 | ... 93 | ], 94 | 95 | editions: [ 96 | { 97 | type: String, # сущность/раздел базы (edition) 98 | id: Int, # id издания 99 | name: String, # наименование издания 100 | name_type: null, # тип издания (если пусто - то обычное бумажное издание произведения) 101 | title: String, # заголовок собранный из автора+названия+типа издания, пример: "Стивен Кинг «Волки Кальи» (издание)" 102 | description: String, # описание издания. текст может содержать a-тэги на сущности базы 103 | image: Url, # ссылка на обложку издания 104 | image_preview: Url, # ссылка на превью обложки 60х~90 105 | url: Url, # ссылка на страницу издания в ФЛ-базе 106 | 107 | year: Year, # год выхода издания 108 | published: Boolean, # издание вышло (1 - опубликовано / 0 - запланировано к выходу) 109 | lang: String, # язык издания 110 | lang_code: String, # код языка издания 111 | copies: Int, # тираж 112 | pages: Int, # количество страниц 113 | isbns: [ ], # строковый массив ISBN 114 | 115 | creators: { # массив авторов/составителей/издательств - т.е. тех, кто принял участие в выходе издания 116 | authors: [ # авторы произведений 117 | { 118 | type: String, # сущность. могут быть "autor" или "art" (для графических) 119 | id: Int, # id автора 120 | name: String, # имя автора 121 | is_opened: Boolean, # открыт ли автор 122 | }, 123 | ... 124 | ], 125 | compiler: [], # составители издания (сборника/антологии). структура такая же как в authors 126 | publishers: [ # издательства 127 | { 128 | type: String, # сущность. тут только тип "publisher" 129 | id: Int, # id издательства 130 | name: String, # наименование издательства 131 | }, 132 | ... 133 | ] 134 | }, 135 | series: [ # серии, в которые входит издание 136 | { 137 | type: String # тип (series) 138 | id: Int, # id серии 139 | name: String, # название серии 140 | is_opened: Boolean, # открыта ли страница серии 141 | }, 142 | ... 143 | ], 144 | }, 145 | ... 146 | ], 147 | 148 | } 149 | ``` 150 | Примечание: 151 | * Список всех типов и их заглушек есть в [файлах конфигурации](config.md) 152 | 153 | 154 | ## Получение миникарточек по поисковому запросу 155 | 156 | Основная json-выдача поиска по базе. Разбита по блоки соответвующие сегментам базы: авторы/произведения/издания. Отдается с учетом релевантности найденнему по запросу. 157 | Структура ответа - формат миникарточек. 158 | 159 | Запрос 160 | ``` 161 | GET /search-txt?q={text} 162 | ``` 163 | 164 | Параметры 165 | ``` 166 | text - слово или фраза для поиска по фл-базе (название произведения, имя автора) 167 | ``` 168 | 169 | Пример 170 | > [/search-txt?q=Мартин](https://api.fantlab.ru/search-txt?q=Мартин) - Выдача по запросу "Мартин" 171 | 172 | Ответ 173 | ``` 174 | соответвует выдачи миникарточек (см. выше на этой странице) 175 | ``` 176 | 177 | 178 | ## Получение миникарточек по их ID 179 | 180 | Запрос на множественную выдачу позиций библиобазы (авторов/произведений/изданий) по id. 181 | 182 | Запрос 183 | ``` 184 | GET /search-ids?a={autor_ids}&w={work_ids}&e={edition_ids} 185 | ``` 186 | 187 | Параметры 188 | ``` 189 | autor_ids - список id-авторов 190 | work_ids - список id-произведений 191 | edition_ids - список id-издания 192 | ``` 193 | id передаются через запятую. Не более 200 позиций. 194 | 195 | Пример 196 | > [/search-ids?a=1,2&w=1,11&e=3,31,1033](https://api.fantlab.ru/search-ids?a=1,2&w=1,11&e=3,31,1033) - Выдача данных карточек авторов с id 1 и 2, произведений 1 и 11, издания 3, 31, 1033 (3 не выдастся, т.к. издания с таким ID нет в базе) 197 | 198 | _Примечание: данный api-запрос используются на страницах самого ФЛ для формирование всплывающих подсказок (превью) ссылок на сегменты базы._ 199 | 200 | Ответ 201 | ``` 202 | соответвует выдачи миникарточек (см. выше на этой странице) 203 | ``` 204 | -------------------------------------------------------------------------------- /Docs/search.md: -------------------------------------------------------------------------------- 1 | # Поиск по библиографической базе 2 | 3 | Общие замечания по выдаче: 4 | 1. Все запросы, кроме общего поиска, поддерживают пагинацию. На одной странице выдается по 25 результатов, максимально возможное общее количество результатов равно 1000. 5 | 2. Во всех ответах сервера есть поле *attrs*, содержащее список полей в выдаче *matches*. Каждое поле обозначено именем и целочисленным типом. Например, "1" - Int, "7" - String. 6 | ## Общая структура ответа 7 | ``` 8 | { 9 | attrs: { # список полей в выдаче 10 | {attr}: Int, 11 | ... 12 | }, 13 | error: String, # текст ошибки, если есть 14 | fields: [ # список полей, по которым осуществляется поиск 15 | ...: String, 16 | ... 17 | ], 18 | matches: [ # список найденных результатов 19 | { 20 | ... 21 | }, 22 | ... 23 | ], 24 | time: Float, # длительность поиска в секундах 25 | total: Int, # общее количество результатов 26 | total_found: Int, # общее количество найденных результатов (но получить можно максимум total) 27 | type: String, # категория поиска 28 | warning: String, # предупреждение, если есть 29 | words: { 30 | {word}: { 31 | docs: Int, # количество найденных совпадений по данному слову 32 | hits: Int # количество найденных уникальных совпадений по данному слову 33 | }, 34 | ... 35 | } 36 | } 37 | ``` 38 | 39 | 40 | ## Поиск авторов 41 | 42 | Запрос 43 | ``` 44 | GET /search-autors?q={query}&page={page}&onlymatches={0|1} 45 | ``` 46 | 47 | Параметры 48 | ``` 49 | query - строка поиска. В качестве разделителя используется "+" 50 | page - номер страницы (необязательный; по-умолчанию 1) 51 | onlymatches - выдавать только содержимое массива matches (необязательный; по-умолчанию 0) 52 | ``` 53 | 54 | Пример 55 | > [/search-autors?q=Asimov&page=1&onlymatches=1](https://api.fantlab.ru/search-autors?q=Asimov&page=1&onlymatches=1) - поиск по фразе "Asimov" 56 | 57 | Ответ (при запросе с параметром **onlymatches=1**) 58 | ``` 59 | [ 60 | { 61 | autor_id: Int, # id автора 62 | birthyear: Int, # год рождения 63 | country: String, # страна 64 | country_id: Int, # id страны 65 | deathyear: Int, # год смерти 66 | doc: Int, # ? 67 | editioncount: Int, # количество изданий 68 | is_opened: Boolean, # открыта ли страница автора 69 | markcount: Int, # количество оценок 70 | midmark: Int, # средняя оценка автора * 100 71 | moviecount: Int, # количество фильмов (экранизаций и т.д.) 72 | name: String, # имя в оригинале 73 | pseudo_names: String, # список псевдонимов 74 | responsecount: Int, # количество отзывов 75 | rusname: String, # русскоязычное имя 76 | weight: Int # степень релевантности (влияет на порядковый номер в выдаче - чем больше, тем выше) 77 | }, 78 | ... 79 | ] 80 | ``` 81 | 82 | 83 | ## Поиск произведений 84 | *TODO: нуждается в структоризации полей* 85 | 86 | Запрос 87 | ``` 88 | GET /search-works?q={query}&page={page}&onlymatches={0|1} 89 | ``` 90 | 91 | Параметры 92 | ``` 93 | query - строка поиска. В качестве разделителя используется "+" 94 | page - номер страницы (необязательный; по-умолчанию 1) 95 | onlymatches - выдавать только содержимое массива matches (необязательный; по-умолчанию 0) 96 | ``` 97 | 98 | Пример 99 | 100 | > [/search-works?q=Asimov&page=1&onlymatches=1](https://api.fantlab.ru/search-works?q=Asimov&page=1&onlymatches=1) - поиск по фразе "Asimov" 101 | 102 | Ответ (при запросе с параметром **onlymatches=1**) 103 | ``` 104 | [ 105 | { 106 | all_autor_name: String, # список всех авторов в оригинале 107 | all_autor_rusname: String, # список всех авторов на русском языке (без bb-тегов) 108 | altname: String, # ? 109 | autor1_id: Int, # id 1-го автора 110 | autor1_is_opened: Boolean, # открыта ли страница 1-го автора 111 | autor1_rusname: String, # русскоязычное имя 1-го автора 112 | autor2_id: Int, # id 2-го автора 113 | autor2_is_opened: Boolean, # открыта ли страница 2-го автора 114 | autor2_rusname: String, # русскоязычное имя 2-го автора 115 | autor3_id: Int, # id 3-го автора 116 | autor3_is_opened: Boolean, # открыта ли страница 3-го автора 117 | autor3_rusname: String, # русскоязычное имя 3-го автора 118 | autor4_id: Int, # id 4-го автора 119 | autor4_is_opened: Boolean, # открыта ли страница 4-го автора 120 | autor4_rusname: String, # русскоязычное имя 4-го автора 121 | autor5_id: Int, # id 5-го автора 122 | autor5_is_opened: Boolean, # открыта ли страница 5-го автора 123 | autor5_rusname: String, # русскоязычное имя 5-го автора 124 | doc: Int, # ? 125 | fullname: String, # полное название произведения (русскоязычное + оригинальное) 126 | keywords: String, # ключевые слова 127 | level: Int, # ? 128 | markcount: Int, # количество оценок 129 | midmark: [ 130 | ...: Float # средняя оценка (не рейтинг) 131 | ], 132 | name: String, # оригинальное название 133 | name_eng: String, # англоязычное название типа произведения 134 | name_show_im: String, # русскоязычное название типа произведения 135 | parent_work_id: Int, # ? 136 | parent_work_id_present: Int, # ? 137 | pic_edition_id: String, # ? 138 | pic_edition_id_auto: Int, # id сопоставленного издания (назначается автоматически) 139 | rusname: String, # русскоязычное название 140 | weight: Int, # степень релевантности 141 | work_id: Int, # id произведения 142 | year: Int # год издания 143 | }, 144 | ... 145 | ] 146 | ``` 147 | 148 | 149 | ## Поиск изданий 150 | 151 | Запрос 152 | ``` 153 | GET /search-editions?q={query}&page={page}&onlymatches={0|1} 154 | ``` 155 | 156 | Параметры 157 | ``` 158 | query - строка поиска. В качестве разделителя используется "+" 159 | page - номер страницы (необязательный; по-умолчанию 1) 160 | onlymatches - выдавать только содержимое массива matches (необязательный; по-умолчанию 0). Если query - это ISBN, то при onlymatches=0 список обернут в шаблонный объект, но из полей только matches и total. 161 | ``` 162 | 163 | Пример 164 | 165 | > [/search-editions?q=Asimov&page=1&onlymatches=1](https://api.fantlab.ru/search-editions?q=Asimov&page=1&onlymatches=1) - поиск по фразе "Asimov" 166 | 167 | Ответ (при запросе с параметром **onlymatches=1**) 168 | ``` 169 | [ 170 | { 171 | autors: String, # список авторов (могут присутствовать bb-теги) 172 | comment: String, # комментарий 173 | compilers: String, # список составителей (могут присутствовать bb-теги) 174 | correct: Int, # уровень проверенности издания (0 - красный, 1 - желтый, 2 - зеленый) 175 | doc: Int, # ? 176 | edition_id: Int, # id издания 177 | isbn1: String, # список isbn с разделителями ("-") 178 | isbn2: String, # список isbn без разделителей 179 | name: String, # название (могут присутствовать bb-теги) 180 | notes: String, # примечания 181 | plan_date: ?, # ? 182 | publisher: String, # издательство (могут присутствовать bb-теги) 183 | series: String, # серия (могут присутствовать bb-теги) 184 | weight: Int, # степень релевантности 185 | year: Int # год издания 186 | }, 187 | ... 188 | ] 189 | ``` 190 | 191 | 192 | ## Поиск книжных серий 193 | 194 | Запрос 195 | ``` 196 | GET /search-series?q={query}&page={page}&onlymatches={0|1} 197 | ``` 198 | 199 | Параметры 200 | ``` 201 | query - строка поиска. В качестве разделителя используется "+" 202 | page - номер страницы (необязательный; по-умолчанию 1) 203 | onlymatches - выдавать только содержимое массива matches (необязательный; по-умолчанию 0) 204 | ``` 205 | 206 | Пример 207 | 208 | > [/search-series?q=Лавкрафт&page=1&onlymatches=1](https://api.fantlab.ru/search-series?q=Лавкрафт&page=1&onlymatches=1) - поиск по фразе "Лавкрафт" 209 | 210 | Ответ (при запросе с параметром **onlymatches=1**) 211 | ``` 212 | [ 213 | { 214 | comment: String, # комментарий 215 | description: String, # описание (могут присутствовать bb-теги) 216 | doc: Int, # ? 217 | editions_count: Int, # количество изданий в серии 218 | name: String, # название 219 | publisher: String, # издательство (могут присутствовать bb-теги) 220 | publisher_alt_names: String, # ? 221 | publisher_comment: String, # ? 222 | publisher_description: String, # ? 223 | publisher_name: String, # ? 224 | publisher_notes: String, # ? 225 | publishers: String, # полный список изданий 226 | series_id: Int, # id книжной серии 227 | weight: Int, # степень релевантности 228 | year_close: Int, # год закрытия серии 229 | year_open: Int, # год открытия серии 230 | }, 231 | ... 232 | ] 233 | ``` 234 | 235 | 236 | ## Поиск премий 237 | 238 | Запрос 239 | ``` 240 | GET /search-awards?q={query}&page={page}&onlymatches={0|1} 241 | ``` 242 | 243 | Параметры 244 | ``` 245 | query - строка поиска. В качестве разделителя используется "+" 246 | page - номер страницы (необязательный; по-умолчанию 1) 247 | onlymatches - выдавать только содержимое массива matches (необязательный; по-умолчанию 0) 248 | ``` 249 | 250 | Пример 251 | 252 | > [/search-awards?q=Asimov&page=1&onlymatches=1](https://api.fantlab.ru/search-awards?q=Asimov&page=1&onlymatches=1) - поиск по фразе "Asimov" 253 | 254 | Ответ (при запросе с параметром **onlymatches=1**) 255 | ``` 256 | [ 257 | { 258 | award_id: Int, # id премии 259 | country: String, # страна вручения 260 | country_id: Int, # id страны вручения 261 | description: String, # описание 262 | doc: Int, # ? 263 | lang_id: Int, # id языка премии 264 | name: String, # название 265 | notes: String, # примечания 266 | rusname: String, # русскоязычное название 267 | type: Int, # ? 268 | weight: Int, # степень релевантности 269 | year_close: Int, # год окончания вручения премии 270 | year_open: Int # год старта вручения премии 271 | }, 272 | ... 273 | ] 274 | ``` 275 | 276 | ## Поиск персон 277 | 278 | Запрос 279 | ``` 280 | GET /search-persons?q={query}&page={page}&onlymatches={0|1} 281 | ``` 282 | 283 | Параметры 284 | ``` 285 | query - строка поиска. В качестве разделителя используется "+" 286 | page - номер страницы (необязательный; по-умолчанию 1) 287 | onlymatches - выдавать только содержимое массива matches (необязательный; по-умолчанию 0) 288 | ``` 289 | 290 | Пример 291 | 292 | > [/search-persons?q=Лавкрафт&page=1&onlymatches=1](https://api.fantlab.ru/search-persons?q=Лавкрафт&page=1&onlymatches=1) - поиск по фразе "Лавкрафт" 293 | 294 | 295 | Ответ (при запросе с параметром **onlymatches=1**) 296 | ``` 297 | [ 298 | { 299 | allnames: String, # список имен (русскоязычное, оригинальное и т.д.) 300 | biography: String, # биография 301 | birthyear: Int, # год рождения 302 | country: String, # страна 303 | country_id: Int, # id страны 304 | deathyear: Int, # год смерти 305 | doc: Int, # ? 306 | name: String, # русскоязычное имя 307 | person_id: Int, # id персоны 308 | type: String, # тип персоны (итоговая ссылка для перехода на страницу персоны на сайте: https://fantlab.ru/{type}{person_id}) 309 | weight: Int # степень релевантности 310 | }, 311 | ... 312 | ] 313 | ``` 314 | 315 | 316 | ## Поиск издательств 317 | 318 | Запрос 319 | ``` 320 | GET /search-publishers?q={query}&page={page}&onlymatches={0|1} 321 | ``` 322 | 323 | Параметры 324 | ``` 325 | query - строка поиска. В качестве разделителя используется "+" 326 | page - номер страницы (необязательный; по-умолчанию 1) 327 | onlymatches - выдавать только содержимое массива matches (необязательный; по-умолчанию 0) 328 | ``` 329 | 330 | Пример 331 | 332 | > [/search-publishers?q=Москва&page=1&onlymatches=1](https://api.fantlab.ru/search-publishers?q=Москва&page=1&onlymatches=1) - поиск по фразе "Москва" 333 | 334 | Ответ (при запросе с параметром **onlymatches=1**) 335 | ``` 336 | [ 337 | { 338 | alt_names: String, # список альтернативных названий издтельства 339 | city: String, # город 340 | comment: String, # комментарий 341 | country: String, # страна 342 | country_id: Int, # id страны 343 | description: String, # описание (могут присутствовать bb-теги) 344 | doc: Int, # ? 345 | name: String, # название 346 | notes: String, # заметки 347 | publisher_id: Int, # id издательства 348 | weight: Int, # степень релевантности 349 | year_close: Int, # год закрытия 350 | year_open: Int # год открытия 351 | }, 352 | ... 353 | ] 354 | ``` 355 | 356 | 357 | ## Поиск фильмов 358 | 359 | Запрос 360 | ``` 361 | GET /search-films?q={query}&page={page}&onlymatches={0|1} 362 | ``` 363 | 364 | Параметры 365 | ``` 366 | query - строка поиска. В качестве разделителя используется "+" 367 | page - номер страницы (необязательный; по-умолчанию 1) 368 | onlymatches - выдавать только содержимое массива matches (необязательный; по-умолчанию 0) 369 | ``` 370 | 371 | Пример 372 | 373 | > [/search-films?q=Лавкрафт&page=1&onlymatches=1](https://api.fantlab.ru/search-films?q=Лавкрафт&page=1&onlymatches=1) - поиск по фразе "Лавкрафт" 374 | 375 | Ответ (при запросе с параметром **onlymatches=1**) 376 | ``` 377 | [ 378 | { 379 | actors: String, # список актеров 380 | country: String, # список стран производства 381 | description: String, # описание 382 | director: String, # список режиссеров 383 | doc: Int, # ? 384 | film_id: Int, # id фильма 385 | name: String, # оригинальное название 386 | rusname: String, # русскоязычное название 387 | screenwriter: String, # список сценаристов 388 | tagline: String, # слоган 389 | weight: Int, # степень релевантности 390 | year: Int # год 391 | }, 392 | ... 393 | ] 394 | ``` 395 | 396 | 397 | ## Поиск статей 398 | 399 | Запрос 400 | ``` 401 | GET /search-articles?q={query}&page={page}&onlymatches={0|1} 402 | ``` 403 | 404 | Параметры 405 | ``` 406 | query - строка поиска. В качестве разделителя используется "+" 407 | page - номер страницы (необязательный; по-умолчанию 1) 408 | onlymatches - выдавать только содержимое массива matches (необязательный; по-умолчанию 0) 409 | ``` 410 | 411 | Пример 412 | 413 | > [/search-articles?q=Лавкрафт&page=1&onlymatches=1](https://api.fantlab.ru/search-articles?q=Лавкрафт&page=1&onlymatches=1) - поиск по фразе "Лавкрафт" 414 | 415 | Ответ (при запросе с параметром **onlymatches=1**) 416 | ``` 417 | [ 418 | { 419 | article_id: Int, # id статьи 420 | autor: String, # автор 421 | comment: String, # комментарий 422 | doc: Int, # ? 423 | name: String, # название 424 | source: String, # источник статьи 425 | text: String, # текст 426 | weight: Int, # степень релевантности 427 | year: Int # год публикации 428 | }, 429 | ... 430 | ] 431 | ``` 432 | 433 | ## Поиск терминов 434 | 435 | Запрос 436 | ``` 437 | GET /search-terms?q={query}&page={page}&onlymatches={0|1} 438 | ``` 439 | 440 | Параметры 441 | ``` 442 | query - строка поиска. В качестве разделителя используется "+" 443 | page - номер страницы (необязательный; по-умолчанию 1) 444 | onlymatches - выдавать только содержимое массива matches (необязательный; по-умолчанию 0) 445 | ``` 446 | 447 | Пример 448 | 449 | > [/search-terms?q=Анабиоз&page=1&onlymatches=1](https://api.fantlab.ru/search-terms?q=Анабиоз&page=1&onlymatches=1) - поиск по фразе "Анабиоз" 450 | 451 | Ответ (при запросе с параметром **onlymatches=1**) 452 | ``` 453 | [ 454 | { 455 | term_id: Int, # id термина 456 | title: String, # название 457 | synonyms: String, # синонимы 458 | work_count: Int, # кол-во связанных произведений 459 | film_count: Int # кол-во связанных фильмов 460 | }, 461 | ... 462 | ] 463 | ``` 464 | 465 | ## Общий поиск 466 | 467 | Запрос 468 | ``` 469 | GET /searchmain?q={query} 470 | ``` 471 | 472 | Параметры 473 | ``` 474 | query - строка поиска. В качестве разделителя используется "+" 475 | ``` 476 | 477 | Пример 478 | 479 | > [/searchmain?q=Лавкрафт](https://api.fantlab.ru/searchmain?q=Лавкрафт) - поиск по фразе "Лавкрафт" 480 | 481 | Ответ (см. [общая структура ответа](#Общая-структура-ответа) и наборы полей для отдельных запросов) 482 | ``` 483 | [ 484 | ..., # список авторов 485 | ..., # список произведений 486 | ..., # список изданий 487 | ..., # список серий 488 | ..., # список премий 489 | ..., # список персон 490 | ..., # список издательств 491 | ..., # список фильмов 492 | ..., # список статей 493 | ... # список терминов 494 | ] 495 | ``` 496 | Примечания: 497 | 1. Запрос не поддерживает пагинацию 498 | 2. По каждой категории поиска выдается максимум 10 результатов, отсортированных по убыванию релевантности (*weight*) 499 | 3. Параметр **onlymatches=1** не работает (кроме случая, когда query - ISBN, тогда выдается просто массив результатов) 500 | -------------------------------------------------------------------------------- /Docs/subscriptions.md: -------------------------------------------------------------------------------- 1 | # Подписки 2 | ## Подписка на оповещения о новых произведениях или изданиях автора 3 | Запрос 4 | ``` 5 | GET https://fantlab.ru/notification/subscribe/autors/{id}/{works|editions}.json 6 | ``` 7 | Параметры 8 | ``` 9 | id - id автора 10 | cookie - авторизационный хэдер (fl_s=*) 11 | ``` 12 | Пример 13 | ``` 14 | GET https://fantlab.ru/notification/subscribe/autors/133/works.json - подписка на оповещения о новых произведениях Дж. Р.Р. Мартина 15 | ``` 16 | Ответ 17 | ``` 18 | { 19 | id: Int, # id подписки 20 | status: Boolean # успешно ли выполнена операция 21 | } 22 | ``` 23 | ## Подписка на оповещения о новых изданиях с переводами переводчика 24 | Запрос 25 | ``` 26 | GET https://fantlab.ru/notification/subscribe/translators/{id}/editions.json 27 | ``` 28 | Параметры 29 | ``` 30 | id - id переводчика 31 | cookie - авторизационный хэдер (fl_s=*) 32 | ``` 33 | Пример 34 | ``` 35 | GET https://fantlab.ru/notification/subscribe/translators/1/editions.json - подписка на оповещения о новых изданиях с переводами И.Г. Гуровой 36 | ``` 37 | Ответ 38 | ``` 39 | { 40 | id: Int, # id подписки 41 | status: Boolean # успешно ли выполнена операция 42 | } 43 | ``` 44 | ## Отмена подписки на оповещения 45 | Запрос 46 | ``` 47 | GET https://fantlab.ru/notification/unsubscribe/{id}.json 48 | ``` 49 | Параметры 50 | ``` 51 | id - id подписки 52 | cookie - авторизационный хэдер (fl_s=*) 53 | ``` 54 | Пример 55 | ``` 56 | GET https://fantlab.ru/notification/unsubscribe/1.json - отписка от оповещений по подписке №1 57 | ``` 58 | Ответ 59 | ``` 60 | { 61 | status: Boolean # успешно ли выполнена операция 62 | } 63 | ``` 64 | ## Подписка на блог 65 | Запрос (повторный запрос - отписка) 66 | ``` 67 | /GET /editblog{id}subscriber 68 | ``` 69 | Параметры 70 | ``` 71 | id - id блога 72 | cookie - авторизационный хэдер (fl_s=*) 73 | ``` 74 | Пример 75 | ``` 76 | /GET https://fantlab.ru/editblog{id}subscriber 77 | ``` 78 | Ответ 79 | ``` 80 | { 81 | is_subscribed: String # on/off 82 | } 83 | ``` 84 | ## Подписка на комментарии к статье в блоге 85 | Запрос (повторный запрос - отписка) 86 | ``` 87 | /GET /edittopic{id}subscriber 88 | ``` 89 | Параметры 90 | ``` 91 | id - id статьи 92 | cookie - авторизационный хэдер (fl_s=*) 93 | ``` 94 | Пример 95 | ``` 96 | /GET https://fantlab.ru/edittopic{id}subscriber 97 | ``` 98 | Ответ 99 | ``` 100 | { 101 | is_subscribed: String # on/off 102 | } 103 | ``` 104 | ## Подписка на новые сообщения в теме форума 105 | Запрос (повторный запрос - отписка) 106 | ``` 107 | /GET /editforumtopic{id}subscriber 108 | ``` 109 | Параметры 110 | ``` 111 | id - id темы 112 | cookie - авторизационный хэдер (fl_s=*) 113 | ``` 114 | Пример 115 | ``` 116 | /GET https://fantlab.ru/editforumtopic{id}subscriber 117 | ``` 118 | Ответ 119 | ``` 120 | { 121 | is_subscribed: String # on/off 122 | } 123 | ``` 124 | -------------------------------------------------------------------------------- /Docs/terms.md: -------------------------------------------------------------------------------- 1 | # Термины (Букопедия) 2 | 3 | ## Список терминов 4 | 5 | Запрос 6 | ``` 7 | GET /terms?letter={letter}&sort={sort} 8 | ``` 9 | 10 | Параметры 11 | ``` 12 | letter - первая буква названия, от А до Я, от A до Z (необязательный; по умолчанию любая [пустая строка]) 13 | sort - вариант сортировки (необязательный; по умолчанию по названию [title]) 14 | * id - по id термина 15 | * title - по названию 16 | * work_count - по количеству привязанных произведений 17 | * film_count - по количеству привязанных фильмов/сериалов и т.п. 18 | ``` 19 | 20 | Пример 21 | > [/terms?letter=А&sort=work_count](https://api.fantlab.ru/terms?letter=А&sort=work_count) - термины на букву "А", отсортированные по количеству привязанных произведений 22 | 23 | Ответ: 24 | ``` 25 | [{ 26 | film_count: Int, # количество привязанных фильмов 27 | is_synonym: Boolean, # 1 - синоним (ссылка на термин), 0 - полноценный термин 28 | term_id: Int, # id термина 29 | title: String, # название (синонима, если это синоним, или самого термина в противном случае) 30 | term_title: String, # название термина 31 | work_count: Int # количество привязанных произведений 32 | }] 33 | ``` 34 | 35 | ## Термин 36 | 37 | Запрос 38 | ``` 39 | GET /term/{id}?sort={sort} 40 | ``` 41 | 42 | Параметры 43 | ``` 44 | sort - вариант сортировки (необязательный; по умолчанию по дате публикации/выхода в прокат [year]) 45 | * rating - по рейтингу (применимо только к произведениям) 46 | * markcount - по количеству оценок (применимо только к произведениям) 47 | * rusname - по русскому названию 48 | * name - по оригинальному названию 49 | * year - для произведений - по дате публикации , для фильмов - по дате выхода в прокат 50 | ``` 51 | 52 | Пример 53 | > [/term/18?sort=rating](https://api.fantlab.ru/term/18?sort=rusname) - термин "Анабиоз", сортировка произведений и фильмов - по русскому названию 54 | 55 | Ответ: 56 | ``` 57 | { 58 | film_blocks: { |null # блоки связанных фильмов, если есть 59 | {block_id}: { # id блока (см. константы) 60 | id: Int, # id блока (совпадает с block_id) 61 | list: [{ # список фильмов в блоке 62 | country: String, # страны производства 63 | director: String, # режиссеры 64 | film_id: Int, # id фильма 65 | name: String, # оригинальное название 66 | rusname: String, # русское название 67 | term_comment: String, # комментарий к связке "термин-фильм" 68 | type: Int, # тип (фильм, сериал и тд); фактически совпадает с block_id 69 | year: Int, # год выпуска 70 | year2: Int|null # год окончания трансляции (для сериалов) 71 | }] 72 | } 73 | }, 74 | related_terms: [{ # связанные термины 75 | term_id: Int, # id термина 76 | title: String # название 77 | }], 78 | source: String, # источник описания 79 | source_link: String, # ссылка на источник описания 80 | synonyms: [{ # список синонимов 81 | synonym: String # синоним 82 | }], 83 | term_id: Int, # id термина 84 | text: String, # описание 85 | title: String, # название 86 | works_blocks: { |null # блоки связанных произведений, если есть 87 | ... # см. * 88 | } 89 | } 90 | ``` 91 | \* - совпадает с выдачей `works_blocks` в [API автора](https://github.com/FantLab/FantLab-API/blob/master/Docs/author.md#расширенная-информация) + `term_comment` в каждом отдельном произведении 92 | -------------------------------------------------------------------------------- /Docs/translator.md: -------------------------------------------------------------------------------- 1 | # Переводчик 2 | 3 | ## Основная информация 4 | Запрос 5 | ``` 6 | GET /translator/{id} 7 | ``` 8 | Параметры 9 | ``` 10 | id - id переводчика 11 | ``` 12 | 13 | Пример: 14 | > [/translator/1](https://api.fantlab.ru/translator/1) - переводчик Ирина Гавриловна Гурова 15 | 16 | Ответ: 17 | ``` 18 | { 19 | age: Int, # возраст на данный момент или на момент смерти 20 | articles: [ # список статей, на данный момент всегда пустой 21 | ...: ?|null 22 | ], 23 | anons: String, # биография с ограничением в 500 символов (ака превью) 24 | biography_notes: String, # примечание к биографии 25 | biography_source: String, # источник биографии 26 | birthday: Date, # дата рождения 27 | countries: [ # список стран 28 | { 29 | country_id: Int, # id страны 30 | name: String # страна 31 | }, 32 | ... 33 | ], 34 | curator_id: Int, # id куратора 35 | curator_name: String, # логин куратора 36 | deathday: Date, # дата смерти 37 | has_advanced_awards: Boolean, # ? 38 | id: Int, # id переводчика 39 | image: String, # ссылка на картинку произведения (обложку по умолчанию) 40 | image_preview: String, # ссылка на превью картинки произведения 41 | name: String, # имя / фамилия 42 | name_orig: String, # имя / фамилия в оригинале (для иностранных переодчиков) 43 | name_rp: String, # имя / фамилия в родительном падеже 44 | name_short: String, # имя (инициалы) / фамилия 45 | name_short_rp: String, # имя (инициалы) / фамилия в родительном падеже 46 | name_sort: String, # полное ФИО для сортировки 47 | notes: String, # ? 48 | person_type: String, # тип персоны (в данном случае всегда translator) 49 | photo: ?, # ? 50 | pseudo_id: Int, # id псевдонима 51 | pseudo_name: ?|null, # ? 52 | sex: Int, # пол (1 - мужской, 2 - женский) 53 | show_in_list: Boolean, # ? 54 | translated_from: String, # "переводчик с ..." 55 | translated_to: String # "переводчик на ..." 56 | } 57 | ``` 58 | 59 | ## Расширенная информация 60 | 61 | Запрос 62 | ``` 63 | GET /translator/{id}/extended?sort={year|autor|type} 64 | ``` 65 | Параметры 66 | ``` 67 | id - id переводчика 68 | sort - вариант сортировки переведенных произведений (необязательный; по-умолчанию year) 69 | * year - по году издания перевода 70 | * autor - по автору произведения 71 | * type - по типу произведения 72 | ``` 73 | Пример: 74 | > [/translator/1](https://api.fantlab.ru/translator/1) - переводчик Ирина Гавриловна Гурова 75 | 76 | Ответ: 77 | ``` 78 | В выдачу к основной информации добавляются следующие поля: 79 | 80 | biography: String, # полная биография 81 | awards: [ 82 | { 83 | award_icon: String, # ссылка на логотип премии 84 | award_id: Int, # id премии 85 | award_in_list: Int, # ? 86 | award_is_opened: Boolean, # открыта ли страница премии 87 | award_name: String, # название премии 88 | award_rusname: String, # русскоязычное название премии 89 | contest_id: Int, # id конкурса 90 | contest_name: String, # название конкурса (обычно сопадает с годом) 91 | contest_year: Int, # год проведения конкурса 92 | cw_id: Int, # ? 93 | cw_is_winner: Int, # ? 94 | cw_postfix: String, # ? 95 | cw_prefix: String, # ? 96 | nomination_id: Int|null, # id номинации 97 | nomination_name: String|null, # название номинации 98 | nomination_rusname: String|null, # русскоязычное название номинации 99 | work_id: Int, # id награжденного произведения (0, если награда относится не к произведению) 100 | work_name: String, # название награжденного произведения 101 | work_rusname: String, # русскоязычное название награжденного произведения 102 | work_year: Int|null # год публикации произведения 103 | }, 104 | ... 105 | ], 106 | sorted_works: [ # список id переведенных произведений, отсортированных в соответствии с переданным типом 107 | ...: String 108 | ], 109 | translated: [ # список переведенных произведений 110 | {translated_work_string_id}: { 111 | author: { # карточка автора произведения 112 | ... 113 | }, 114 | editions: [ # список изданий 115 | { # карточка издания 116 | ... 117 | }, 118 | ... 119 | ], 120 | work: { # карточка произведения 121 | ... 122 | }, 123 | }, 124 | ... 125 | ], 126 | 127 | ``` 128 | В выдаче переведенных произведений карточки произведения, издания и автора сделаны в формате [миникарточек](search-ids.md) 129 | 130 | 131 | ## Список наград отдельно 132 | Запрос 133 | ``` 134 | GET /translator/{id}/awards?sort={byorder|byaward|bychrono} 135 | ``` 136 | Параметры 137 | ``` 138 | id - id переводчика 139 | sort - вариант сортировки наград (необязательный; по-умолчанию bychrono) 140 | * byorder - по порядку 141 | * byaward - по премиям 142 | * bychrono - по хронологии 143 | ``` 144 | Пример 145 | ``` 146 | GET /translator/1/awards?sort=byorder - награды И.Г. Гуровой по порядку 147 | ``` 148 | Ответ 149 | ``` 150 | [ 151 | { 152 | ... # те же самые поля, что и в translator -> awards 153 | } 154 | ] 155 | ``` 156 | **Nota bene**: 157 | 158 | список отдается без разбиения по категориям 159 | 160 | ## Полная биография отдельно 161 | Запрос 162 | ``` 163 | GET /translator/{id}/biography 164 | ``` 165 | Параметры 166 | ``` 167 | id - id переводчика 168 | ``` 169 | Пример 170 | ``` 171 | GET /translator/1/biography - полная биография И.Г. Гуровой 172 | ``` 173 | Ответ 174 | ``` 175 | Те же самые поля, что и в выдаче основной информации + поле biography из расширенной 176 | ``` 177 | 178 | ## Библиография переведенных произведений отдельно 179 | Запрос 180 | ``` 181 | GET /translator/{id}/translated?sort={year|autor|type} 182 | ``` 183 | Параметры 184 | ``` 185 | id - id переводчика 186 | sort - вариант сортировки переведенных произведений (необязательный; по-умолчанию year) 187 | * year - по году издания перевода 188 | * autor - по автору произведения 189 | * type - по типу произведения 190 | ``` 191 | Пример 192 | ``` 193 | GET /translator/1/translated - список переведенных произведений И.Г. Гуровой 194 | ``` 195 | Ответ 196 | ``` 197 | Те же самые поля, что и в выдаче основной информации + поля sorted_works и translated из расширенной 198 | ``` 199 | -------------------------------------------------------------------------------- /Docs/user.md: -------------------------------------------------------------------------------- 1 | # Пользователь 2 | 3 | ## Основная информация 4 | 5 | Запрос 6 | ``` 7 | GET /user/{id} 8 | ``` 9 | 10 | Параметры 11 | ``` 12 | id - id пользователя 13 | ``` 14 | 15 | Пример 16 | > [/user/1](https://api.fantlab.ru/user/1) - юзеринфо creator'а 17 | 18 | Ответ 19 | ``` 20 | { 21 | user_id: Int, # id юзера 22 | login: String, # логин юзера 23 | avatar: Url, # ссылка на аватарку юзера 24 | fio: String, # фио юзера (необязательный) 25 | sex: String, # пол (m - мужской, w - женский) 26 | birthday: DateTime, # дата рождения 27 | birthday_iso: DateTime, # дата рождения в ISO 8601 28 | 29 | user_class: Int, # id класса развития 30 | class_name: String, # названия класса развития на сайте 31 | level: Float, # развитие в классе 32 | 33 | location: String, # место жительства в текстовом виде (строка текста) 34 | country_name: String, # страна 35 | country_id: Int, # id страны по внутренний базе 36 | city_name: String, # город 37 | city_id: Int, # id города по внутренний базе 38 | 39 | date_of_reg: DateTime, # дата регистрации на сайте 40 | date_of_reg_iso: DateTime, # дата регистрации на сайте в ISO 8601 41 | date_of_last_action: DateTime, # дата последнего посещения сайта 42 | date_of_last_action_iso: DateTime, # дата последнего посещения сайта в ISO 8601 43 | user_timer: Int, # сколько времени был на сайте за последение 30 дней (секунды) 44 | sign: String, # подпись под постами на форуме 45 | 46 | markcount: Int, # оценено произведений 47 | responsecount: Int, # написано отзывов на произведения 48 | descriptioncount: Int, # написно аннотаций 49 | classifcount: Int, # сделано классификаций произведений 50 | votecount: Int, # кол-во получил плюсов за свои отзывы 51 | 52 | topiccount: Int, # открыл тем на форуме 53 | messagecount: Int, # написал постов на форуме 54 | bookcase_count: Int, # заведено книжных поток 55 | 56 | curator_autors: Int, # кол-во курируемых позиций на сайте 57 | tickets_count: Int, # написано тикитов в базу сайта 58 | 59 | autor_id: Int, # id автора в базе FL, если юзер является автором 60 | autor_name: String, # имя 61 | autor_name_orig: String, # имя англ. 62 | autor_is_opened: Boolean, # открыт ли этот автор на фл (0 - нет / 1 - да) 63 | 64 | blog_id: Int, # id авторской колонки юзера (если есть) 65 | 66 | block: Boolean, # юзер в бане (0 - нет / 1 - да) 67 | date_of_block: DateTime, # дата начало бана 68 | date_of_block_iso: DateTime, # дата начало бана в ISO 8601 69 | date_of_block_end: DateTime, # дата окончание бана (если null - бан вечный) 70 | date_of_block_end_iso: DateTime # дата окончание бана в ISO 8601 (если null - бан вечный) 71 | } 72 | ``` 73 | 74 | 75 | ## Список отзывов 76 | см. [Docs/responses.md#Отзывы посетителя](../Docs/responses.md#Отзывы-посетителя) 77 | 78 | 79 | ## Узнать id по login 80 | 81 | Запрос 82 | ``` 83 | GET /userlogin?usersearch={login} 84 | ``` 85 | 86 | Пример 87 | > [userlogin?usersearch=creator](https://api.fantlab.ru/userlogin?usersearch=creator) - id юзера "creator" 88 | 89 | Ответ 90 | ``` 91 | { 92 | user_id: Int 93 | } 94 | ``` 95 | 96 | Примечание: при отсутствии такого логина вернется `user_id: 0` 97 | -------------------------------------------------------------------------------- /Docs/work.md: -------------------------------------------------------------------------------- 1 | # Произведение 2 | 3 | ## Основная информация 4 | ``` 5 | GET /work/{id} 6 | ``` 7 | 8 | Пример: 9 | > [/work/1](https://api.fantlab.ru/work/1) - Дэн Симменс "Гиперион" 10 | 11 | 12 | Ответ: 13 | ``` 14 | { 15 | work_id: Int, # id произведения 16 | last_modified: DateTime, # время последнего изменения данных 17 | last_modified_iso: DateTime, # время последнего изменения данных в ISO 8601 18 | work_name: String, # название произведения 19 | work_name_orig: String, # оригинальное название (анг или родной) 20 | work_name_alts: [ # массив альтернативных названий произведения 21 | ...: String?, 22 | ... 23 | ], 24 | work_name_bonus: String, # дополнение к названию 25 | authors: [ 26 | { 27 | type: String, # тип персоны (autor, art) 28 | id: Int, # id типа персоны ( по формату /{type}/{id} однозначно укажет на нужную персону ) 29 | name: String, # имя фамилия 30 | name_orig: String, # имя фамилия (анг или родной) 31 | is_opened: Int, # открыта ли страница автора (1 - да, 0 - нет) 32 | }, 33 | ... 34 | ], 35 | work_year: Int, # год публикации произведения 36 | work_year_of_write: Int, # год написания произведения (если указан) 37 | work_description: String, # аннотация 38 | work_description_author: String, # автор анотации (может содержать bb-тэги) 39 | work_notes: String, # примечание 40 | lang: String, # язык написания 41 | lang_code: String, # код языка написания 42 | 43 | title: String, # автор(ы)+название в формате "Дэн Симмонс «Гиперион»" 44 | image: String, # ссылка на картинку произведения (обложку по умолчанию) 45 | image_preview: String, # ссылка на превью картинки произведения 46 | 47 | publish_statuses: [ # для неопубликованных о статусе проивзедения ("не закончено", "в планах", ...) 48 | ...: String, 49 | ... 50 | ], 51 | 52 | work_published: Int, # вышло ли произведени (0 - не опубликовано, 1 - опубликовано) 53 | work_preparing: Int, # запланированное произведени (1 - "в планах автора") 54 | work_notfinished: Int, # не законченое произведение (1 - "не окончено") 55 | work_lp: Int, # доступен линговоанаолиз произведения (0 - "нет" / 1 - "есть") 56 | public_download_file: Int, # есть файл для скачивания/чтения (1 - "доступно для свободного чтения") 57 | 58 | rating: { 59 | rating: Float, # рейтинг (до сотых, пр.: "8.91") 60 | voters: Int, # кол-во оценок 61 | }, 62 | val_midmark_by_weight: Float, # рейтинг (дубль) 63 | val_voters: Int, # кол-во оценок (дубль) 64 | val_responsecount: Int, # кол-во отзывов на произведение 65 | 66 | work_type_id: Int, # id типа произведения 67 | work_type: String, # тип провездения (роман, повесть, рассказ & etc) 68 | work_type_name: String, # тип произведения на английском 69 | 70 | work_parent: Int, # >0 для неактивных частей - если является частью другого произведение, то тут его id 71 | } 72 | ``` 73 | 74 | ## Расширенная информация 75 | ``` 76 | GET /work/{id}/extended 77 | ``` 78 | в расширенной информации о произведении добавляются поля: 79 | *awards - премии автора 80 | editions_info - статистика изданий 81 | editions_blocks - издания ворка. разбиты по блокам типов 82 | translations - переводчики 83 | classificatory - классификация 84 | children - дерево вложенных ворков, обычно для ворка-цикла 85 | parents - входит в 86 | films - экранизации и новеллизации 87 | la_resume - линговопрофиль произведения* 88 | 89 | Пример: 90 | > [/work/1/extended](https://api.fantlab.ru/work/1/extended) - Дэн Симменс "Гиперион" 91 | 92 | 93 | Ответ: 94 | ``` 95 | { 96 | work_id: Int, # id произведения 97 | ... все поля обычной карточки произведения (см. выше) и добаляются новые: ... 98 | 99 | awards: { # объект с массивами полученных премий и номинаций 100 | nom: [], win [] |null # формат массива аналогичен выдаче в карточке автора 101 | } 102 | 103 | editions_info: { ... }, # статистическая информация об изданиях обновсящихся к данному произведению 104 | editions_blocks: { ... }, # массив изданий, разбитый по типам изданий 105 | # соответствуют выдачи в карточке вывода всех изданий автора (см: author.md#Список-изданий ) 106 | 107 | translations: [ # переводчики произведения. массив объектов, разбитый по языкам перевода 108 | { 109 | lang_code: String, # двухбуквенный код языка: ru, en и & 110 | lang_id: Int, # id кода языка 111 | lang: String, # название языка на русском 112 | translations: [ # массив переводов произведения на данный язык 113 | { 114 | titles: [ # массив названий данного перевода 115 | { # (редко, но встречается что один перевод выходит под назными названиями) 116 | title: String, # название перевода 117 | count: Int, # кол-во издний с этим переводом 118 | }, 119 | ... 120 | ], 121 | year: Int, # год перевода 122 | translators: [ # переводчики данного перевода 123 | { 124 | type: String, # тип персоны (тут всегда "translator") 125 | id: Int, # id тпиа персоны (переводчика) 126 | name: String, # имя фамилия полностью 127 | short_name: String, # И.Фамилия 128 | }, 129 | ... 130 | ], 131 | }, 132 | ... 133 | ], 134 | }, 135 | ... 136 | ], 137 | 138 | classificatory: { # классификация произведения 139 | total_count: Int, # кол-во сделаных классификаций от юзеров 140 | genre_group: [ # массив свойств классификатора 141 | { 142 | genre_group_id: Int, # id группы свойств классификатора 143 | label: String, # название группы свойств на русском 144 | genre: [ 145 | { 146 | genre_id: Int, # id тип жанра 147 | label: String, # название пункта классификатора на русском 148 | votes: Int, # кол-во классификаций, где указан этот пункт 149 | percent: Float, # процент классификаций, где указан этот пункт (от 0 до 1, с шагом 0.1) 150 | genre: [ ... ] , # вложенные типы (если есть). рекурсивное вложение в массиве такого же вида 151 | }, 152 | ... 153 | ], 154 | ... 155 | }, 156 | ... 157 | ], 158 | }, 159 | 160 | work_root_saga: [ # название циклов, куда водит данное произвдеение 161 | { 162 | work_id: Int, # id цикла (ворка) 163 | work_name: String, # название 164 | work_type: String, # тип произведения на русском 165 | work_type_id: Int, # id типа произведния 166 | work_year: null # год публикации 167 | }, 168 | ... 169 | ], 170 | 171 | parents: { # подробнее в какие произведения/циклы/журналы входит данный ворк 172 | {cycles}: [ # массив циклов 173 | [ # цепочка ворков цикла от корня (пример: цикл "Галактическая история" -> цикл "Основание"-> ...) 174 | { 175 | work_id: Int, # id ворка 176 | ... # формат выдачи объъекта аналогичен work_root_saga 177 | }, 178 | ... 179 | ] 180 | ], 181 | {digest}: [ [...], [...] ] # массив журналов 182 | }, 183 | 184 | 185 | children: [ # произвдения, входящик в данное произведение/цикл 186 | { ... } # формат массива аналогичен выдаче works_blocks->{type}->list в карточке автора 187 | ], 188 | 189 | la_resume: [ String, ... ] # лингоанализ произведения. массив строк 190 | 191 | films: { # фильмы, разбиты на блоки по типам отношения к произведению 192 | {screen_version}: [ # экранизации 193 | { 194 | film_id: Int, 195 | type: Int, # id типа фильм (фильм, сериал, анимация и пр) 196 | year: Int 197 | name: String, 198 | rusname: String, 199 | country: String, 200 | director: String, 201 | }, 202 | ... 203 | ], 204 | {novelization}: [], # новелизации 205 | {screenplay}: [], # как сценарий для фильма 206 | }, 207 | 208 | ``` 209 | 210 | ## Похожие произведения 211 | Запрос 212 | ``` 213 | GET /work/{id}/similars 214 | ``` 215 | 216 | Пример: 217 | > [/work/1/similars](https://api.fantlab.ru/work/1/similars) - похожие проивезедения на Дэн Симменс "Гиперион" 218 | 219 | Ответ 220 | 221 | ``` 222 | { 223 | [ 224 | type: String, # сущность/раздел базы (в данном случае всегда "work") 225 | id: Int, # id произведения 226 | name: String, # имя 227 | ... 228 | ``` 229 | *Вывод полностью соответевует выдачи мини-карточек при запросе по id. 230 | см. блок works в разделе [Docs/search-ids.md#Получение-миникарточек-по-их-ID](search-ids.md#Получение-миникарточек-по-их-ID)* 231 | 232 | 233 | 234 | 235 | 236 | ## Выставление/удаление оценки 237 | Запрос 238 | ``` 239 | GET https://fantlab.ru/work{id_1}/ajaxsetmark{mark}towork{id_2} 240 | ``` 241 | Параметры 242 | ``` 243 | id_1 - id произведения, со страницы которого ставится оценка 244 | mark - оценка 0-10, 0 - удаление оценки 245 | id_2 - id произведения, которому ставится оценка 246 | cookie - авторизационный хэдер (fl_s=*) 247 | ``` 248 | Пример 249 | ``` 250 | /GET https://fantlab.ru/work92/ajaxsetmark10towork1 - поставить оценку 10 "Гипериону" Дэна Симмонса со страницы цикла "Песни Гипериона" 251 | ``` 252 | Ответ 253 | ``` 254 | { 255 | markcount: Int, # новое количество оценок 256 | midmark: Float # новый рейтинг 257 | } 258 | ``` 259 | 260 | ## Классификация 261 | Действие доступно только для посетителей с уровнем "Философ" и выше. 262 | 263 | Запрос 264 | ``` 265 | GET /genrevote{work_id}?wg{id_1}=on&wg{id_2}=on&wg{id_3}=on&wg{id_4}=on... 266 | ``` 267 | Параметры 268 | ``` 269 | work_id - id произведения 270 | id_1, id_2, ... - индексы характеристик (обязательно должен быть выбран хотя бы один пункт в следующих разделах: Жанры/поджанры, Место действия, Время действия, Возраст читателя) 271 | cookie - авторизационный хэдер (fl_s=*) 272 | ``` 273 | Ответ 274 | ``` 275 | HTML-страница 276 | ``` 277 | 278 | ## Добавление похожего произведения 279 | Запрос 280 | ``` 281 | GET https://fantlab.ru/work{work_id}/analog{analog_work_id}/add 282 | ``` 283 | Параметры 284 | ``` 285 | work_id - id произведения 286 | analog_work_id - id произведения, которое хотим добавить в качестве похожего 287 | cookie - авторизационный хэдер (fl_s=*) 288 | ``` 289 | Пример 290 | ``` 291 | GET https://fantlab.ru/work1/analog4325/add - добавить "Дюну" Фрэнка Герберта в качесте похожего на "Гиперион" произведения 292 | ``` 293 | Ответ 294 | ``` 295 | { 296 | info: { 297 | marks_count: Int, # количество оценок у похожего произведения 298 | marks_sum: Int, # сумма оценок (чтобы можно было посчитать среднюю оценку) 299 | responses_count: Int, # количество отзывов у похожего произведения 300 | user_mark: Int|null, # оценка пользователя (null, если нет) 301 | user_response: Int|null # id отзыва (null, если нет) 302 | }, 303 | pair_id: Int, # id пары 304 | status: String # статус добавления (ok) 305 | } 306 | ``` 307 | 308 | ## Удаление похожего произведения 309 | Запрос 310 | ``` 311 | GET https://fantlab.ru/work{work_id}/analog{analog_work_id}/remove 312 | ``` 313 | Параметры 314 | ``` 315 | work_id - id произведения 316 | analog_work_id - id похожего произведения 317 | X-Session - авторизационный сессрил\онный хэдер (или cookie fl_s=*) 318 | ``` 319 | Пример 320 | ``` 321 | GET https://fantlab.ru/work1/analog4325/remove - удалить "Дюну" Фрэнка Герберта из списка похожих на "Гиперион" произведений 322 | ``` 323 | Ответ 324 | ``` 325 | { 326 | remove_status: Boolean, # ? 327 | status: String # статус удаления (ok) 328 | } 329 | ``` 330 | -------------------------------------------------------------------------------- /History.md: -------------------------------------------------------------------------------- 1 | # Лог версий Fantlab-API 2 | Ключевая информация об изменениях в API 3 | 4 | ### v0.9.3 (06.08.2019) 5 | * аворизованная работа с личными книжными полками юзера (подборками) - [/Docs/bookcases.md](/Docs/bookcases.md) 6 | 7 | ### v0.9.22 (18.06.2019) 8 | * добавлено описание способа авторизации через хидер "X-Session" - /login - [/Docs/auth.md](/Docs/auth.md) 9 | * в выдаче произведений добавлен вывод языка - поля lang и lang_code- [/Docs/work.md](/Docs/work.md) 10 | 11 | ### v0.9.21 (03.03.2019) 12 | * добавлена выдача "Список новостей сайта" - /news - [/Docs/news.md](/Docs/news.md) 13 | * добавлена выдача "Новинки и планы издательств, авторов" /pubnews - [/Docs/pubnews.md](/Docs/pubnews.md) 14 | 15 | ### v0.9.20 (11.12.2018) 16 | * добавлена выдача "похожих произведений" /work{id}/similars в стандарте миникарточек. [/Docs/work.md#Похожие-произведения](/Docs/work.md#Похожие-произведения) 17 | 18 | 19 | ### v0.9.19 (07.12.2018) 20 | * добавлена выдача search-txt - это универсальная поисковая выдача в стандарте миникарточек (пока только для авторов и произведений). [/Docs/search-ids.md](/Docs/search-ids.md) 21 | 22 | 23 | ### v0.9.18 (18.08.2018) 24 | * изменен вывод классификатора в ворке - что дать кол-во классификаций - добавился "надуровень" в иерархию - подробнее в доке [/Docs/work.md](/Docs/work.md) 25 | 26 | 27 | ### v0.9.17 (25.05.2018) 28 | * добавлен вывод оценок юзера - подробнее в доке [/Docs/marks.md](/Docs/marks.md) 29 | 30 | ### v0.9.16 (10.05.2018) 31 | * в api издания причесан вывод доп.изображений - сделано без нумерных массивов - подробнее в доке [/Docs/edition.md](/Docs/edition.md) 32 | 33 | ### v0.9.15 (19.02.2018) 34 | * изменена выдача спискок отзывов: добавлено поле total_count - общее кол-во отзывов по данного списка, сами списки перенесены в items - подробнее в доке [/Docs/responses.md](/Docs/responses.md) 35 | 36 | 37 | ### v0.9.14 (08.02.2018) 38 | * добавлена выдача карточки юзера - https://api.fantlab.ru/user/1 39 | * приведены в общему названию имена полей выдач списков отзывов на: ворк, автора, юзера; добавлен `mark`(оценка) в выдачи - https://api.fantlab.ru/work/1/responses 40 | 41 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 FantLab 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Fantlab-API 2 | 3 | Публичный репозиторий по API библиографического краудсорсингового портала **fantlab.ru**. 4 | Предназначен для: 5 | * документирования текущего состояния API 6 | * взаимодействия программистов FL и пользователей API через систему *Issues*/*Pull Requests* 7 | 8 | ## Вводная информация 9 | 1. API работает в тестовом режиме, текущая версия: **v0.9.\*** (*[см.историю изменений](History.md)*). До версии **1.0** возможны большие изменения в выдачах. 10 | 2. Домен для запросов - **https://api.fantlab.ru**. 11 | 3. Возможные HTTP-коды ответов: *200* (успех), *404* (ошибка запроса). 12 | 4. Из-за особенностей серверного языка (бэкенд написан на *Perl*) в выдачах уделено мало внимания типизации данных, например, вместо числа может прийти строка (e.g. `"work_id":"1"`). Это не баг. В подобных случаях в документации указан не действительный тип поля (строка), а тот, к которому можно автоматически привести (e.g. `work_id: Int`). 13 | 5. В текстовых данных могут встретиться LINK-тэги - отсылки на сущности базы - для удобства для этого используются формат html-тэга *a href*). Пример: `“notes”:”Переиздание сборника рассказов Стивен Кинг «Бегущий человек»”`. Полный список сущностей базы: *autor*, *art*, *dictor*, *translator*, *person*, *work*, *edition*, *series*, *publisher*, *film*, *award*, *contest*, *user*, *topic*, *article*, *blog*, *blogarticle*. Также могут встретиться и bb-тэги вида *[user]* и т.п.. По возможности от них избавляемся, но они могут до сих пор проскакивать. 14 | 6. В случае, если тип поля в документации обозначен как *null*, это означает одно из двух: либо поле может вообще отсутствовать, либо поле есть, но его значение равно *null*. Впрочем, с точки зрения конечного пользователя это одно и то же. 15 | 7. Для удобства описания были введены дополнительные типы данных: *Boolean* ("0" (false) / "1" (true)), *Date* (строка в формате `yyyy-MM-dd`), *DateTime* (строка в формате `yyyy-MM-dd HH:mm:ss`), *Url* (ссылка на файл/картинку, обычно без протокола). 16 | 8. Если какое-нибудь поле может присутствовать или быть неравным *null* только при определенном переданном параметре, то в описании типа в этом случае указан соответствующий параметр (например, `# [biblio_blocks] список произведений`). Если поле не равно *null* при любом переданном параметре, в описании типа указан параметр `[any]`. 17 | 18 | ## Содержание 19 | 1. [Константы](Docs/config.md#Константы) 20 | 2. Поиск 21 | * [Миникарточки элементов базы](Docs/search-ids.md) 22 | * [Получение миникарточек по поисковому запросу](Docs/search-ids.md#Получение-миникарточек-по-поисковому-запросу) 23 | * [Получение миникарточек по их ID](Docs/search-ids.md#Получение-миникарточек-по-их-id) 24 | * [Поиск по библиографической базе](Docs/search.md#Поиск-по-библиографической-базе) 25 | * [Общий поиск](Docs/search.md#Общий-поиск) 26 | * [Поиск авторов](Docs/search.md#Поиск-авторов) 27 | * [Поиск произведений](Docs/search.md#Поиск-произведений) 28 | * [Поиск изданий](Docs/search.md#Поиск-изданий) 29 | * [Поиск книжных серий](Docs/search.md#Поиск-книжных-серий) 30 | * [Поиск премий](Docs/search.md#Поиск-премий) 31 | * [Поиск персон](Docs/search.md#Поиск-персон) 32 | * [Поиск издательств](Docs/search.md#Поиск-издательств) 33 | * [Поиск фильмов](Docs/search.md#Поиск-фильмов) 34 | * [Поиск статей](Docs/search.md#Поиск-статей) 35 | * [Поиск терминов](Docs/search.md#Поиск-терминов) 36 | * [Поиск по форуму](Docs/search-forum.md#Поиск-по-форуму) 37 | * [Поиск по блогам](Docs/search-blogs.md#Поиск-по-блогам) 38 | 3. [Автор](Docs/author.md#Автор) 39 | * [Список авторов](Docs/author.md#Список-авторов) 40 | * [Основная информация](Docs/author.md#Основная-информация) 41 | * [Список изданий](Docs/author.md#Список-изданий) 42 | * [Список наград](Docs/author.md#Список-наград-отдельно) 43 | * [Список отзывов](Docs/responses.md#Отзывы-на-одно-произведение) 44 | 4. [Произведение](Docs/work.md#Произведение) 45 | * [Основная информация](Docs/work.md#Основная-информация) 46 | * [Расширенная информация](Docs/work.md#Расширенная-информация) 47 | * [Список отзывов](Docs/responses.md#Отзывы-на-одно-произведение) 48 | * [Похожие произведения (Аналоги)](Docs/responses.md#Похожие-произведения) 49 | * [Выставление/удаление оценки](Docs/work.md#Выставлениеудаление-оценки) 50 | * [Классификация](Docs/work.md#Классификация) 51 | * [Добавление похожего произведения](Docs/work.md#Добавление-похожего-произведения) 52 | * [Удаление похожего произведения](Docs/work.md#Удаление-похожего-произведения) 53 | 5. [Издание](Docs/edition.md#Издание) 54 | * [Основная информация](Docs/edition.md#Основная-информация) 55 | * [Расширенная информация](Docs/edition.md#Расширенная-информация) 56 | 6. [Премии](Docs/awards.md#Премии) 57 | * [Список премий](Docs/awards.md#Список-премий) 58 | * [Премия](Docs/awards.md#Премия) 59 | * [Конкурс](Docs/awards.md#Конкурс) 60 | 7. [Переводчик](Docs/translator.md#Переводчик) 61 | * [Основная информация](Docs/translator.md#Основная-информация) 62 | * [Список наград](Docs/translator.md#Список-наград-отдельно) 63 | 8. [Диктор](Docs/dictor.md#Диктор) 64 | 9. [Издательства](Docs/publisher.md#Издательства) 65 | * [Список издательств](Docs/publisher.md#Список-издательств) 66 | * [Топ-30 издательств](Docs/publisher.md#Топ-30-издательств) 67 | 10. [Термины](Docs//terms.md#Термины-Букопедия) 68 | * [Список терминов](Docs/terms.md#Список-терминов) 69 | * [Термин](Docs/terms.md#Термин) 70 | 11. [Пользователь](Docs/user.md#Пользователь) 71 | * [Основная информация](Docs/user.md#Основная-информация) 72 | * [Список оценок](Docs/marks.md#Оценки-посетителя) 73 | * [Список отзывов](Docs/responses.md#Отзывы-посетителя) 74 | * [Узнать id по login](Docs/user.md#Узнать-id-по-login) 75 | 12. [Отзывы](Docs/responses.md#Отзывы) 76 | * [Отзывы на все произведения автора](Docs/responses.md#Отзывы-на-все-произведения-автора) 77 | * [Отзывы на одно произведение](Docs/responses.md#Отзывы-на-одно-произведение) 78 | * [Отзывы посетителя](Docs/responses.md#Отзывы-посетителя) 79 | * [Новые отзывы на сайте](Docs/responses.md#Новые-отзывы-на-сайте) 80 | * [Плюсование/минусование отзыва](Docs/responses.md#Плюсованиеминусование-отзыва) 81 | 13. [Новости](Docs/news.md#Новости) 82 | * [Список новостей сайта](Docs/news.md#список-новостей) 83 | 14. [Новинки и планы издательств, авторов](Docs/pubnews.md) 84 | * [Новинки издательств](Docs/pubnews.md) 85 | * [Планы издательств](Docs/pubnews.md) 86 | * [Планы авторов](Docs/pubnews.md) 87 | 15. Авторизация 88 | * [OAuth](Docs/oauth.md#oauth-авторизация) 89 | * [Основная](Docs/auth.md#Авторизация) 90 | 16. [Подписки](Docs/subscriptions.md#Подписки) 91 | * [Подписка на оповещения о новых произведениях/изданиях автора](Docs/subscriptions.md#Подписка-на-оповещения-о-новых-произведениях-или-изданиях-автора) 92 | * [Подписка на оповещения о новых изданиях с переводами переводчика](Docs/subscriptions.md#Подписка-на-оповещения-о-новых-изданиях-с-переводами-переводчика) 93 | * [Отмена подписки на оповещения](Docs/subscriptions.md#Отмена-подписки-на-оповещения) 94 | * [Подписка на блог](Docs/subscriptions.md#Подписка-на-блог) 95 | * [Подписка на комментарии к статье в блоге](Docs/subscriptions.md#Подписка-на-комментарии-к-статье-в-блоге) 96 | * [Подписка на новые сообщения в теме форума](Docs/subscriptions.md#Подписка-на-новые-сообщения-в-теме-форума) 97 | 17. [Книжные полки](Docs/bookcases.md#Книжные-полки) 98 | * [Создание книжной полки](Docs/bookcases.md#Создание-книжной-полки) 99 | * [Удаление книжной полки](Docs/bookcases.md#Удаление-книжной-полки) 100 | * [Содержимое полки произведений](Docs/bookcases.md#Содержимое-полки-произведений) 101 | * [Содержимое полки изданий](Docs/bookcases.md#Содержимое-полки-изданий) 102 | * [Содержимое полки фильмов](Docs/bookcases.md#Содержимое-полки-фильмов) 103 | * [Добавление или удаление произведения с книжной полки](Docs/bookcases.md#Добавление-или-удаление-произведения-с-книжной-полки) 104 | * [Добавление или удаление издания с книжной полки](Docs/bookcases.md#Добавление-или-удаление-издания-с-книжной-полки) 105 | * [Добавление или удаление фильма с книжной полки](Docs/bookcases.md#Добавление-или-удаление-фильма-с-книжной-полки) 106 | * [Добавление комментария к item](Docs/bookcases.md#Добавление-комментария-к-item) 107 | 18. [Личка](Docs/private-messages.md#Личка) 108 | * [Отправка/сохранение в черновик сообщения](Docs/private-messages.md#Отправкасохранение-в-черновик-сообщения) 109 | * [Подтверждение отправки черновика](Docs/private-messages.md#Подтверждение-отправки-черновика) 110 | * [Отмена отправки черновика](Docs/private-messages.md#Отмена-отправки-черновика) 111 | 19. [Рекомендации](Docs/recommendations.md#Рекомендации) 112 | * [Удаление рекомендации в мусорку](Docs/recommendations.md#Удаление-рекомендации-в-мусорку) 113 | * [Правка мусорки рекомендаций](Docs/recommendations.md#Правка-мусорки-рекомендаций) 114 | 20. [Форум](Docs/forum.md#Форум) 115 | * [Плюсование/минусование поста](Docs/forum.md#Плюсованиеминусование-поста) 116 | 21. Прочее 117 | * [Теги, ссылки и пр.](Docs/other.md#Теги-ссылки-и-пр) 118 | -------------------------------------------------------------------------------- /Scheme/08365A56-B1B2-4914-95B1-A05BF710A533.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FantLab/FantLab-API/d98bc2b17f87d17b1654d8ff5ae974fac1e3e719/Scheme/08365A56-B1B2-4914-95B1-A05BF710A533.png -------------------------------------------------------------------------------- /Scheme/FL Sections Schema.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Draw.io Diagram 5 | 6 | 7 | 8 | 9 |
10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /Scheme/FL Sections Schema.md: -------------------------------------------------------------------------------- 1 | Схема осноных разделов и сервисов Фантлаба 2 | -------------------------------------------------------------------------------- /Scheme/FL Sections Schema.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FantLab/FantLab-API/d98bc2b17f87d17b1654d8ff5ae974fac1e3e719/Scheme/FL Sections Schema.png --------------------------------------------------------------------------------